What is a scoped local development setup for microservices?
A scoped setup starts from one observation: for any given task, you rarely need all ten services running at once. You need the one or two you are changing, the handful they call directly, and something that answers for everything else. The setup becomes a per-task decision instead of a fixed "run the whole system" script.
For each task, sort services into three tiers:
- Edited: the services whose code you are changing. They run locally at full fidelity, with live reload, a debugger and real logs, because this is where your feedback loop lives.
- Direct dependencies: services and datastores the edited code calls. Run them in the lightest form that still exercises your change. That can be a prebuilt container, a local database with seed data, or a contract-faithful fake.
- Background: transitive and asynchronous services such as notifications, analytics or search indexing. Stub them, or route the occasional call to a shared remote environment.
Task: change refund logic in orders-api
[EDITED] orders-api ............ local, full fidelity
|
[DEPENDENCY] postgres, payments .... local, lightest form
|
[BACKGROUND] email, analytics ...... stubbed
catalog, auth ......... remote (shared cluster)
Backend and platform engineers on systems with many services benefit most, because every extra container costs memory, startup time and another thing that can fail before the code you care about runs. The classification drives every later choice. It determines which Compose profile you start, what Tilt watches and rebuilds, and which traffic Telepresence routes between your laptop and the cluster.
Task: change refund logic in orders-api
+------------------------- LAPTOP (local) --------------------------+
| [EDITED] full fidelity |
| +--------------------------------------------+ |
| | orders-api | |
| | live reload, debugger, real logs |-----------+ |
| +--------------------------------------------+ | |
| | | | | |
| v v v | |
| [DEPENDENCY] lightest form [BACKGROUND] stubbed | |
| +------------+ +------------+ +--------------------+ | |
| | postgres | | payments | | email, analytics | | |
| | seed data | | container | | (stubs) | | |
| +------------+ +------------+ +--------------------+ | |
| | |
+-----------------------------------------------------------|-------+
|
routed calls v
+--------------------- SHARED CLUSTER (remote) ---------------------+
| [BACKGROUND] remote |
| +-------------+ +-------------+ |
| | catalog | | auth | |
| +-------------+ +-------------+ |
+-------------------------------------------------------------------+
For one task, the edited service runs locally with full tooling, its direct dependencies run locally in their lightest form, email and analytics are stubbed, and calls to catalog and auth are routed to a shared remote cluster.
Why does running every service locally break down?
Start with memory, because it runs out first. The figures below are an illustrative estimate with assumed inputs, not measurements. Substitute your own numbers from your container runtime's stats output.
| Component (assumed) | Count | Assumed RAM each | Subtotal |
|---|---|---|---|
| Application services (JVM/Node/Go mix) | 10 | 400 MB | 4.0 GB |
| Relational databases | 2 | 500 MB | 1.0 GB |
| Message broker | 1 | 1.0 GB | 1.0 GB |
| Container runtime VM overhead | 1 | 1.5 GB | 1.5 GB |
| IDE with language servers | 1 | 2.0 GB | 2.0 GB |
| Browser with dev tools | 1 | 2.0 GB | 2.0 GB |
| OS and background apps | 1 | 3.0 GB | 3.0 GB |
| Total | 14.5 GB |
Under these assumptions, a 16 GB laptop has about 1.5 GB of headroom before a single build runs. A compiler or a test run that needs a few gigabytes pushes the machine into swap. After that, every page fault waits on disk.
The memory shortfall costs engineers time on every inner-loop iteration. Cold-starting ten containers and waiting for health checks can take minutes. A one-line change that should rebuild in seconds stalls because the CPU is busy recompiling services you never touched. The fans spin up constantly, and swap thrashing makes the IDE lag on keystrokes. The work is serialized behind a machine that is overcommitted.
Pointing everything at a shared remote environment avoids the memory problem but adds different costs. Each call across the network adds latency. Other people's deploys make results flaky. You also cannot work offline. Scoping trades between these two failure modes: run locally only the services you need to run, and treat every other service as a stub or a remote dependency.
How do Docker Compose profiles let one file run different subsets?
Compose profiles implement that scoping in a single file. Tag each service with a profiles list, such as core, payments or async-workers. A service with no profiles key always starts, so put the shared foundation there: the database, the message broker and the stubs every workflow needs. Profiled services stay off until you enable them at startup. Use docker compose --profile payments up, repeating the flag for more groups, or set COMPOSE_PROFILES=payments,async-workers in your shell or .env file. A payments engineer then runs the core plus the payments services, and the async workers' containers never start.
Startup ordering needs more care. Plain depends_on waits only until a dependency's container has started, not until the service inside can accept connections. A database may still be replaying its log or creating users when your API connects and crashes. Fixed sleep calls in entrypoints are either too short on a cold machine or waste time on a warm one. Instead, give each dependency a healthcheck that runs a real readiness probe, such as pg_isready for Postgres. Then declare depends_on with condition: service_healthy. Compose holds the dependent service until the probe passes and uses start_period and retries to tolerate slow first boots.
Profiles have limits. The topology you run is one you chose, not the one production runs. Compose service names differ from Kubernetes DNS. Env files replace ConfigMaps and Secrets. Kubernetes has no depends_on, so code that relies on ordering can fail after deploy. Bind mounts are fast on Linux but noticeably slower on macOS and Windows, where files cross a VM boundary.
# docker compose --profile core up -d # foundation + API
# docker compose --profile core --profile payments up -d # add payments
# COMPOSE_PROFILES=core,async-workers docker compose up -d
services:
postgres: # no profiles key: always starts
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: local-dev-only
POSTGRES_DB: app
healthcheck: # ready = accepting connections, not just running
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 3s
retries: 10
start_period: 20s # failures during first boot don't count
rabbitmq: # shared broker, always starts
image: rabbitmq:3
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 10s
retries: 10
start_period: 30s
api:
build: ./api
profiles: [core]
depends_on:
postgres: { condition: service_healthy } # replaces sleep loops
payments:
build: ./payments
profiles: [payments]
depends_on:
postgres: { condition: service_healthy }
rabbitmq: { condition: service_healthy }
worker:
build: ./worker
profiles: [async-workers]
depends_on:
rabbitmq: { condition: service_healthy }
A single compose file where Postgres and RabbitMQ always start, workflow services are grouped by profile, and healthchecks with condition: service_healthy hold each dependent service until its dependencies are ready.
When should you use Tilt for the Kubernetes inner loop?
Tilt fits when production runs on Kubernetes and the slow part of your day is the edit-build-deploy loop. If every change means rebuilding an image, pushing it, and waiting for a rollout, Tilt shortens that cycle while you still test against real manifests, Services and ConfigMaps.
How it works
You describe the environment in a Tiltfile, written in Starlark, a Python-like configuration language. Because it is code, you can loop over services, read environment variables, and include shared fragments instead of copying YAML. A typical file has three parts:
docker_buildtells Tilt how to build each image.k8s_yamlloads the manifests to apply.k8s_resourcegroups workloads and sets port forwards and dependencies between resources.
Running tilt up watches your source files and redeploys when they change.
The speed comes from live_update. Its sync steps copy changed files into the running container, and its run steps execute commands such as reinstalling dependencies when a lockfile changes. A one-line change can then reach the container in seconds, without an image rebuild or pod restart. Tilt also gives you one view of build status, pod health and logs for every service, so you don't have to juggle kubectl logs across terminals.
When to avoid it
Tilt needs a cluster, either a local one or a remote dev namespace, so it adds cost and setup that Compose does not. The Tiltfile becomes infrastructure code, and someone has to own it as services change. File-sync speed also depends on the operating system and the cluster runtime, so test it on your team's actual machines before you standardize on it.
# Tiltfile (Starlark). Run `tilt up` from the repo root.
# Load the Kubernetes manifests you would apply in a real environment.
k8s_yaml(['k8s/postgres.yaml', 'k8s/api.yaml', 'k8s/worker.yaml'])
# Build the API image once, then patch the running container on each change.
docker_build(
'registry.example.com/shop/api',
'./services/api',
live_update=[
# Copy changed files into the container instead of rebuilding the image.
sync('./services/api', '/app'),
# Reinstall dependencies only when the manifest or lockfile changes.
run('npm install',
trigger=['./services/api/package.json',
'./services/api/package-lock.json']),
],
)
# The Tiltfile is code, so similar services can share one definition.
for name in ['worker']:
docker_build(
'registry.example.com/shop/' + name,
'./services/' + name,
live_update=[sync('./services/' + name + '/src', '/app/src')],
)
# Group workloads in the Tilt UI, forward ports and order startup.
k8s_resource('postgres', port_forwards='5432:5432')
k8s_resource('api', port_forwards='8080:8080', resource_deps=['postgres'])
k8s_resource('worker', resource_deps=['postgres'])
A minimal Tiltfile that loads manifests with k8s_yaml, uses docker_build with live_update to sync files and rerun npm install only when the lockfile changes, loops over similar services, and uses k8s_resource to set port forwards and startup dependencies.
How does Telepresence connect a laptop service to a shared cluster?
Telepresence takes the opposite approach. Instead of moving the cluster onto your laptop, it connects your laptop to the cluster. It does two things.
- It intercepts a workload. Requests addressed to an in-cluster service are rerouted to a process running on your machine. You run one service locally, with your debugger and hot reload, while it receives real traffic from its in-cluster callers.
- It joins your laptop to the cluster network. Your machine gets in-cluster networking and DNS, so the local process can call real dependencies by their cluster service names. You don't need stubs or port-forwards for each one.
When it fits
It fits when the service you're changing depends on many heavy services, such as a search cluster, a message broker or a dozen internal APIs, and a reachable shared cluster already runs them. You run only the one service you're editing, and the cluster supplies everything else.
When to avoid it
- Permissions: You need cluster permissions to install and manage intercepts.
- Network: You need a stable network, and offline work isn't possible.
- Shared environments: An intercept on a shared environment can divert a teammate's requests to your laptop. Avoid this unless namespaces or routing rules keep each developer's traffic separate.
Shared cluster or per-developer namespaces
- One shared dev cluster is cheap to run. Teammates contend over the same data, the same deployed versions of each service and the same resource quota.
- Per-developer namespaces remove that contention. They multiply cluster spend, because each developer runs their own copy of the dependencies.
Many teams choose a middle option: they share stateless dependencies and isolate the databases.
How do you keep stubs, seed data and config from drifting?
A stub replaces a dependency you would otherwise run or route to. It only helps if it behaves like the real service. If the payment team renames a field and your stub still returns the old shape, your tests pass locally and fail in staging. Keep stubs in the same repository as the API they imitate, generated from or checked against its published contract. Then add a CI job on the provider side that replays every consumer's recorded expectations against the real service. When the provider breaks a consumer, its build fails. Without that check, a stub is a snapshot that quietly goes stale.
Starting state needs the same discipline. Seed data should come from a script, not from a database dump someone made months ago. The script must also be idempotent, so a developer can run it any number of times and get the same result. For example, a seed script inserts a fixed set of users and orders keyed on hard-coded IDs, using INSERT ... ON CONFLICT DO NOTHING in PostgreSQL. Running it twice changes nothing, and tests can reference those IDs directly. Give each developer their own schema or namespace, derived from their username, so one person's seed run never overwrites another's.
Finally, keep environment configuration in one place. Use a committed defaults file plus a gitignored local overrides file, and have the Compose file, the Tiltfile and the Telepresence workflow all read from that pair. When all three tools load the same variables, a bug you see in one setup reproduces in the others.
-- seed.sql: idempotent seed data for one developer's schema.
-- Run with:
-- psql -v ON_ERROR_STOP=1 -v dev_schema="dev_$USER" -f seed.sql
-- Running it any number of times leaves the schema in the same state.
-- Each developer gets their own schema, so seed runs never collide.
CREATE SCHEMA IF NOT EXISTS :"dev_schema";
SET search_path TO :"dev_schema";
-- Normally migrations own the tables. They are inlined here so the example runs on its own.
CREATE TABLE IF NOT EXISTS users (
id integer PRIMARY KEY,
email text NOT NULL UNIQUE
);
CREATE TABLE IF NOT EXISTS orders (
id integer PRIMARY KEY,
user_id integer NOT NULL REFERENCES users(id),
total_cents integer NOT NULL
);
-- Hard-coded IDs let tests reference these rows directly.
-- ON CONFLICT DO NOTHING turns a second run into a no-op.
INSERT INTO users (id, email) VALUES
(1001, 'alice@example.test'),
(1002, 'bob@example.test')
ON CONFLICT (id) DO NOTHING;
INSERT INTO orders (id, user_id, total_cents) VALUES
(5001, 1001, 2599),
(5002, 1001, 1200),
(5003, 1002, 9900)
ON CONFLICT (id) DO NOTHING;
A PostgreSQL seed script you can run repeatedly: it creates a per-developer schema named after $USER and inserts fixed-ID rows, which ON CONFLICT DO NOTHING keeps from being duplicated.
Which combination of Compose profiles, Tilt and Telepresence should your team choose?
| Team size | Deployment target | Shared cluster? | Typical change scope | Recommended setup | Laptop load | Cluster spend | Maintenance owner |
|---|---|---|---|---|---|---|---|
| Small | VMs or plain containers | No | Whole system | Plain Compose | High | None | Any developer |
| Small to mid | Containers | No | One or two services | Compose profiles | Medium | None | Rotating developer |
| Mid | Kubernetes | No | Several services together | Tilt plus stubs | Medium | None | Platform engineer |
| Mid to large | Kubernetes | Yes | One service | Telepresence plus Compose profiles | Low | Shared cluster | Platform team |
| Large | Kubernetes | Yes, per developer | Any | Fully remote dev environment | Minimal | High | Dedicated platform team |
| Any | Any | No | API contract only | Stubs only | Minimal | None | Owners of each upstream service |
A layering example
Say you are editing the checkout service. Telepresence routes cluster traffic for checkout to the process on your laptop, so it talks to the real inventory and pricing services in the shared cluster. A Compose profile runs a local Postgres and message broker beside it. Your migrations and test messages then stay off shared state, and you avoid running eight services you never touch.
The organisational cost
Each extra layer adds onboarding steps and another place where config can diverge. If nobody owns the dev environment, it decays: stubs fall behind real APIs, profiles reference services that were renamed, and new hires lose their first week to setup. Name an owner and give them time for the work. That time is repaid through shorter inner loops, fewer afternoons spent debugging the environment instead of the code, and new engineers shipping sooner.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to local development microservices, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.