Switch Between Monolith And Microservices

Your stack:

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

  • Docker installed and running
  • Ruby and Bundler installed locally (for bundle commands)

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.

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.