Switch Between Monolith And Microservices
Goal
Start with two Ruby classes in a single project running as a monolith, then extract one into a separate microservice using Graftcode. After that one-time setup, switch freely between monolith and microservice by changing a single configuration value — zero further code changes.
What You'll See
- Create two Ruby classes in the same project — a price calculator and a billing service that calls it directly.
- Host both in a single container as a monolith.
- Extract the price calculator into its own container as a standalone microservice.
- Connect the billing service through a Graft.
- Switch between monolith and microservice by changing one environment variable — no code changes from that point on.
Prerequisites
Step 1. Create a project folder
mkdir ruby-energy-platform cd ruby-energy-platform
Create energy-platform.gemspec:
# frozen_string_literal: true Gem::Specification.new do |spec| spec.name = "energy-platform" spec.version = "1.0.0" spec.authors = ["Example"] spec.summary = "Energy platform - switches between monolith and microservice deployments" spec.license = "MIT" spec.files = Dir["lib/**/*.rb"] spec.require_paths = ["lib"] spec.required_ruby_version = ">= 3.2.0" end
Create Gemfile:
# frozen_string_literal: true source "https://rubygems.org" gemspec
Create .dockerignore in the project root so host-only Bundler output is never copied into the image:
# Do not ship Windows/macOS bundle paths into Linux containers — native gems (e.g. ffi x64-mingw-ucrt) # conflict with Linux (x86_64-linux-gnu) and cause FrozenError / duplicate constant warnings at runtime. vendor/ .bundle/
If you already ran bundle install --path vendor/bundle on Windows, delete vendor/ before docker build (or rely on .dockerignore). Otherwise COPY . /usr/app/ pulls Ruby 3.4 + mingw ffi next to the image’s Ruby 3.3 + Linux ffi, and Gateway fails with FrozenError: can't modify frozen Hash when both versions load.
Step 2. Write the price calculator
Create lib/energy_price_calculator.rb:
# frozen_string_literal: true class EnergyPriceCalculator def self.get_price rand(100..104) end end
Step 3. Write the billing service
Create lib/billing_service.rb:
# frozen_string_literal: true class BillingService def self.calculate_bill(kwh_used) price = EnergyPriceCalculator.get_price kwh_used * price end end
A direct class reference — no Graftcode wiring yet.
Step 4. Host as a monolith
Create a Dockerfile in the project root:
FROM ruby:3.3-bookworm WORKDIR /usr/app COPY . /usr/app/ RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \ && curl -fsSL grft.dev/get/gg | sh && dpkg -i gg.deb && rm gg.deb \ && bundle install \ && apt-get clean && rm -rf /var/lib/apt/lists/* ENV HYPERTUBE_RUBY_RUNTIME_PATH=/usr/local/lib/libruby.so EXPOSE 80 CMD ["gg", ".", "--runtime", "ruby"]
Keep .dockerignore from Step 1 in the repo before building — without it, a host vendor/bundle from bundle install (especially on Windows) is copied in and breaks native gems such as ffi at runtime.
Build and run:
docker build --no-cache --pull -t ruby-energy-platform:test . docker run -d -p 80:80 --name energy_platform ruby-energy-platform:test
gg (Graftcode Gateway) scans the gem project under /usr/app, discovers both classes, and exposes their public class methods. Open http://localhost:80/GV and invoke BillingService.calculate_bill — both classes show up because everything runs in one process.
Step 5. Extract the price calculator as a separate microservice
Create Dockerfile.priceCalculator:
FROM ruby:3.3-bookworm WORKDIR /usr/app COPY . /usr/app/ RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \ && curl -fsSL grft.dev/get/gg | sh && dpkg -i gg.deb && rm gg.deb \ && bundle install \ && apt-get clean && rm -rf /var/lib/apt/lists/* ENV HYPERTUBE_RUBY_RUNTIME_PATH=/usr/local/lib/libruby.so EXPOSE 90 EXPOSE 91 CMD ["gg", ".", "--runtime", "ruby", "--types", "EnergyPriceCalculator", "--httpPort", "91", "--port", "90", "--TCPServer", "--tcpPort=9092"]
The second container uses the same gem layout as the monolith. --types EnergyPriceCalculator exposes only that class as a standalone service while keeping the usual Ruby hosting path (gem root with *.gemspec).
Build and run the dedicated gateway:
docker build --no-cache --pull -f Dockerfile.priceCalculator -t price-calculator-ruby:test . docker network create graftcode_demo docker run -d --network graftcode_demo -p 90:90 -p 91:91 -p 9092:9092 --name price_calculator price-calculator-ruby:test
Open http://localhost:90/GV — only EnergyPriceCalculator is published on this Gateway instance. (This gateway uses --port 90 for the primary listener and --httpPort 91 for the second HTTP stack; Vision is also on 90 at /GV.)
Step 6. Connect the billing service through a Graft
From Vision at http://localhost:90/GV, choose RubyGems and copy the gem install / Bundler snippet.
Merge that gem into the root Gemfile next to gemspec (illustration only — paste Vision's source + gem lines):
# frozen_string_literal: true source "https://rubygems.org" source "https://grft.dev/<uuid>__free" do gem "graft-rubygems-energy-platform_5kg1tc", "1.0.0" end gemspec
Run
rm Gemfile.lock bundle install
locally so Gemfile.lock captures the Graft coordinates, then rebuild the Docker image — the existing RUN bundle install layer pulls the gem during docker build.
Update lib/billing_service.rb to load the Graft and read configuration from GRAFT_CONFIG:
# frozen_string_literal: true require "graft_rubygems_energy_platform_5kg1tc" class BillingService def self.calculate_bill(kwh_used) GraftConfig.set_config(ENV["GRAFT_CONFIG"]) price = EnergyPriceCalculator.get_price kwh_used * price end end
Use the exact require string and namespaces printed in Vision - generated Ruby typically mirrors the hosted types (for example EnergyPriceCalculator and GraftConfig). This single edit is the only code change in the tutorial; topology is now driven entirely by GRAFT_CONFIG, as described in Configure Graft invocation.
Note
In GRAFT_CONFIG, name= is the graft's internal identifier (often like graft.rubygems.energy_platform) — not the hyphenated RubyGems package id. Copy the name= segment from Vision or the generated GraftConfig.
Step 7. Run as a microservice
Rebuild the main image and run it on the Docker network:
docker stop energy_platform docker rm energy_platform docker build --no-cache --pull -t ruby-energy-platform:test . docker run -d --network graftcode_demo -e GRAFT_CONFIG="name=graft.rubygems.energy_platform;host=ws://price_calculator:90/ws;runtime=ruby;modules=/usr/app" -p 80:80 --name energy_platform ruby-energy-platform:test
Call BillingService.calculate_bill from http://localhost:80/GV — results match the monolith, but price selection now crosses the network.
Step 8. Switch back to monolith
docker stop energy_platform docker rm energy_platform docker run -d -e GRAFT_CONFIG="name=graft.rubygems.energy_platform;host=inmemory;runtime=ruby;modules=/usr/app" -p 80:80 --name energy_platform ruby-energy-platform:test
Side-by-side:
# Monolith (in-process) name=graft.rubygems.energy_platform;host=inmemory;runtime=ruby;modules=/usr/app # Microservice (remote) name=graft.rubygems.energy_platform;host=ws://price_calculator:90/ws;runtime=ruby;modules=/usr/app
GRAFT_CONFIG owns the topology — same image, same Ruby source, one environment variable.
Step 9. Prove the remote call
Return to microservice mode, stop price_calculator, and watch calculate_bill fail in Vision until the dependency container restarts — identical behavior to the other language tutorials, proving the billing service now depends on the remote Gateway.
Step 10. Run with a Project Key (recommended for real-world usage)
When you graduate beyond local UUID registries, add --projectKey to each gg invocation (Dockerfile CMD or orchestration env) so RubyGems coordinates and MCP endpoints stay stable — see Use a project key.