Deployment identity

Composite Key

Deployments in SHC are not named entities. Instead, they are identified by a composite key:

tenant + stack + environment = unique deployment

Tenant: Isolation boundary (e.g., default, acme-corp)
Stack: The installed app instance (e.g., nextcloud, my-blog)
Environment: Deployment context (e.g., default, prod, staging)

This design ensures that each deployment has a unique identity without requiring explicit deployment names.

Why Not Named Entities

Traditional platforms often require explicit deployment or instance names. SHC takes a different approach:

Simpler workflow: No need to come up with deployment names
Predictable paths: File locations follow a consistent pattern
Clear scoping: Configuration and secrets naturally map to the composite key
Multi-environment support: Same stack can be deployed multiple times with different environments

Stack Naming

When installing an app, the stack name defaults to the app name:

shc install nextcloud                  # stack="nextcloud", env="default"
shc install nextcloud --stack cloud    # stack="cloud", env="default"
shc install nextcloud -s cloud -e prod # stack="cloud", env="prod"

You can install the same app multiple times with different stack names:

shc install wordpress --stack blog      # First WordPress instance
shc install wordpress --stack shop      # Second WordPress instance

Environment Isolation

Environments provide deployment isolation within a stack. They enable running the same app with different configurations side-by-side.

Common Environment Names

Environment	Purpose
`default`	Default when not specified
`prod`	Production workloads
`staging`	Pre-production testing
`dev`	Development and experimentation

Use Cases

# Same app, different environments
shc install nextcloud -s cloud -e prod      # Production instance
shc install nextcloud -s cloud -e staging   # Staging instance

# Each environment is fully isolated:
# - Separate Docker Compose project
# - Separate data volumes
# - Separate configuration
# - Separate vault secrets

What’s Shared vs Isolated

Aspect	Shared Between Environments?
App definition	Yes (same app.yaml, compose.yaml)
Data volumes	No (each env has own `mounts/` directory)
Config	Inherited but can be overridden per-env
Vault secrets	Can be scoped to environment or shared
Docker network	No (each env has own network)
Container names	No (prefixed with deployment_id)

When to Use Environments

Testing upgrades: Deploy to staging, test, then upgrade prod
Feature branches: Spin up dev environment for testing
Multi-region: Different environments for different regions
Client demos: Isolated demo environments

Docker Integration

The deployment_id (used for Docker Compose project naming) is derived from the composite key:

deployment_id = "{tenant}_{environment}_{stack}"
# Example: "default_prod_nextcloud"

This deployment_id is used for:

Docker Compose project name: docker compose -p {deployment_id}
Container naming: Containers are prefixed with {deployment_id}_
Network naming: Networks are prefixed with {deployment_id}_
Label values: Containers are labeled with shc.tenant, shc.stack, shc.environment

Example container name:

default_nextcloud_prod_web_1
│      │         │    │   │
│      │         │    │   └── Replica number
│      │         │    └── Service name
│      │         └── Environment
│      └── Stack
└── Tenant