shc clone
The shc clone command creates a duplicate of a running deployment, enabling testing, staging environments, or development copies.
Overview
Section titled “Overview”Clone creates a copy of a stack while keeping the original intact. It shares infrastructure with the move command but preserves the source stack.
| Operation | Flow | Original Stack |
|---|---|---|
| Clone | Backup -> Recover | Kept |
| Move | Backup -> Uninstall -> Recover | Deleted |
shc clone
Section titled “shc clone”Create a duplicate of a stack:
# Clone under a new nameshc clone myapp myapp-clone
# Clone and say where the copy may runshc clone myapp myapp-prod --where 'location=hetzner/hel1'
# Clone with all connected stacks (integrations)shc clone myapp myapp-prod --all-connections
# Clone to different environmentshc clone myapp myapp-staging --target-environment staging
# Clone to different tenant (requires permission)shc clone myapp myapp-copy --target-tenant other-org
# Dry run (preview without executing)shc clone myapp myapp-clone --dry-runArguments
Section titled “Arguments”| Argument | Required | Description |
|---|---|---|
<source> | Yes | Source stack name |
<new-name> | Yes | Target stack name (positional) |
| Flag | Default | Description |
|---|---|---|
--where <selector> | none | Where the copy may run, in place of the source’s own --where |
--prefer <selector> | none | Which of those nodes the copy should run on, in place of the source’s own --prefer |
--target-environment | same | Target environment |
--target-tenant | same | Target tenant (requires permission) |
--all-connections, -a | false | Clone entire integration graph |
--rename, -r | none | Rename dependencies: old:new,old2:new2 |
--dry-run | false | Show what would be cloned |
Examples
Section titled “Examples”Basic Clone
Section titled “Basic Clone”# Create a test copy of production databaseshc clone postgres postgres-test
# Output:# Cloning postgres -> postgres-test# v Backing up postgres# v Recovering postgres-test# Clone completeClone with Integrations
Section titled “Clone with Integrations”When a stack has integrations (plugs/sockets), you must use --all-connections to clone the entire graph:
# Clone app and its database togethershc clone myapp myapp-staging --all-connections
# Clone with dependency renamingshc clone myapp myapp-test --all-connections --rename postgres=postgres-testWithout --all-connections, cloning a stack with dependencies will fail:
$ shc clone nextcloud nextcloud-testError: Stack 'nextcloud' has dependencies that would be orphaned: - postgres (provides: postgres-socket)
Use --all-connections to clone the entire integration graph, orunplug dependencies first.Where the Copy Lands
Section titled “Where the Copy Lands”A clone names no node. The copy is a new deployment, and the placement
engine puts it where an install would go: it reads the source deployment’s
own --where and --prefer, or the ones given on the clone in their place,
and picks a node that matches. They are recorded on the copy once the clone
has succeeded, so shc constraint ls and shc explain show them afterwards.
# The copy keeps the source's rules and adds one of its ownshc clone myapp myapp-prod --where 'location=hetzner/hel1' --all-connections
# --dry-run places the copy and prints the plan without cloning anythingshc clone myapp myapp-prod --where 'location=hetzner/hel1' --dry-runA clone that passes --node is refused with X400242SELFLG, which names the
--where to write instead (ce core/selector/flags.go); -n is an unknown
flag; and the API refuses a request body that carries node or node_id
(X400647CLNNOD). A clone whose rules leave no node is refused by name
before anything is backed up.
When the copy lands on another node, the clone performs a full backup -> recover cycle and the data is transferred there.
Clone to Different Environment
Section titled “Clone to Different Environment”# Create staging copy from productionshc clone myapp myapp --target-environment staging
# Note: Same stack name is allowed when environment differsSame-Node Optimization
Section titled “Same-Node Optimization”When cloning to the same node (only name change), SHC uses a fast rename path instead of full backup/recover. This renames:
| Resource | Pattern |
|---|---|
| Deployment record | deployment.stack_name column |
| Deployment directory | {base}/deployments/{tenant}/{stack}/{environment}/ |
| App directory | {base}/apps/{tenant}/{stack}/ |
| Docker Compose project | {tenant}_{environment}_{stack} |
| Docker volumes | {tenant}_{environment}_{stack}_{volume} |
| Vault secrets | tenants/{tenant}/stacks/{stack}/... |
| Schedule records | schedule.stack_name column |
| Backup cache | backup_cache.stack_name column |
Integration Handling
Section titled “Integration Handling”| Scenario | Behavior |
|---|---|
No --all-connections | Reintegrates with existing providers (shares integrations); the copy is held to the source’s node, where those providers are read, and a --where that leaves that node out is refused |
--all-connections | Clones all connected stacks (full backup + recover); the set lands together on the node the engine picks, and each member’s own rules must allow it |
--all-connections, a peer left behind | The set is held to the source’s node until --closure carries the peer too |
| Auto-suffix on collision | Dependencies get -1, -2, etc. suffix |
Name Collision Rules
Section titled “Name Collision Rules”Clone always requires a different name, environment, or tenant from the source:
# These will fail (same name in same scope)$ shc clone myapp myappError: Target stack 'myapp' already exists in tenant 'default', environment 'default'
# These work (different scope)shc clone myapp myapp --target-environment staging # Different environmentshc clone myapp myapp --target-tenant other-org # Different tenantshc clone myapp myapp-copy # Different nameProcess Flow
Section titled “Process Flow”- Preflight - Validate target doesn’t exist, check quota
- Backup - Create coordinated backup of source stack(s)
- Recover - Deploy to target with new name/location
- Integrate - Re-establish integrations (if applicable)