Shared Platform Services

Shared Platform Services represent a repo-scoped architectural tier in Docktree that hosts services shared across multiple git worktrees. Instead of duplicating heavy infrastructure like databases or caches for every worktree instance, Docktree allows developers to define a "platform" stack that remains persistent while individual worktrees connect to it via an isolated external network.

This system provides a balance between isolation and resource efficiency. While application services (API, UI, Workers) are duplicated and isolated per worktree, infrastructure services (PostgreSQL, Redis, S3) can be shared, with optional logical isolation such as per-worktree databases within a single shared database instance.
Sources: internal/config/config.go:42-45, internal/compose/platform.go:68-75, internal/compose/shared_services_e2e_test.go:16-21

Architecture and Synthesis

The system operates by splitting a single Docker Compose project into two distinct synthesized projects: the Platform Project and the Worktree Project.

Synthesis Logic

1. Platform Synthesis: Extracts services defined in the shared.services configuration. It strips host port publishes to prevent collisions and attaches services to a dedicated platform network.
2. Worktree Synthesis: Removes the shared services from the worktree's compose project and adds the platform network as an external network so the worktree services can reach the shared infrastructure.
3. Dependency Management: depends_on edges in worktree services that point to platform services are stripped to ensure the synthesized worktree project remains valid without the platform service definitions.

The following diagram illustrates the relationship between the synthesized projects and the shared network:

Configuration and Tenancy

Shared services are configured in docktree.yml under the shared key. The primary configuration determines the "Kind" of service and its "Tenancy" mode.

Tenancy Modes

Sources: internal/config/config.go:163-172, internal/config/config.go:189-196

Data Structures

type SharedService struct {
	Kind       string                    `yaml:"kind"`
	Tenancy    string                    `yaml:"tenancy"`
	TenantEnv  string                    `yaml:"tenant_env,omitempty"`
	Aliases    []string                  `yaml:"aliases,omitempty"`
	URLEnvs    []string                  `yaml:"url_envs,omitempty"`
	DBNameEnvs []string                  `yaml:"db_name_envs,omitempty"`
	Databases  map[string]SharedDatabase `yaml:"databases,omitempty"`
}

Sources: internal/config/config.go:56-65

Network Isolation and DNS

Docktree ensures that platform services are reachable by worktree services using stable DNS aliases on an external network.

• Platform Network: Named docktree-platform-<repo>-net.
• DNS Aliases: The shared service name and any configured aliases are added to the platform network configuration for each service.
• Port Stripping: Platform services have Ports set to nil during synthesis. This forces all traffic to stay within the Docker network, preventing host-level port conflicts.

Service Provisioning and Rewriting

For services using per_database tenancy, Docktree automates the creation of tenant-specific connection strings.

URL Rewriting Process

When a worktree starts (docktree up), Docktree:

1. Resolves a unique tenant database name based on the repo slug and instance name.
2. Identifies environment variables listed in url_envs (e.g., DATABASE_URL).
3. Rewrites these variables in the worktree containers to point to the new tenant database.
4. Optionally injects the database name into db_name_envs (e.g., POSTGRES_DB) for applications that construct URLs at runtime.

Initialization and Detection

The docktree init command includes specialized logic to detect potential shared services in an existing docker-compose.yml.

Detection Heuristics

• Service Matching: Scans for images matching known infrastructure types (postgres, mysql, redis, etc.).
• Secret Wrappers: Warns if consumer services use tools like infisical or doppler, as these might inject connection strings that Docktree cannot see or rewrite.
• Proposal Generation: Generates a docktree.yml.proposed file with shared.services candidates, allowing users to choose tenancy modes before applying.

Sources: internal/cli/init.go:94-110, internal/cli/init.go:312-332, internal/cli/init_test.go:42-65

Summary

Shared Platform Services enable Docktree to manage complex development environments where heavy stateful services are shared across lightweight, ephemeral git worktrees. By combining automated compose synthesis, network-level isolation, and environment variable rewriting, the system provides a seamless experience that mimics a full local stack while significantly reducing resource overhead and port management complexity.
Sources: internal/compose/platform.go:68-75, internal/cli/up.go:145-155