Full multi-edition guide: DEPLOY.md (Hosted + self-host OSS + self-host Enterprise).
This guide is for operators deploying OSS EnvSync on a single Ubuntu or Debian Docker Swarm host.
For Enterprise self-host, use the private package @envsync-cloud/deploy-enterprise (envsync-deploy-enterprise) from GitHub Packages — not this public flow. See DEPLOY.md § Self-host Enterprise.
- one public Linux host with root or sudo access
- Docker Swarm manager node
- public DNS for the app/api/auth (and optional obs/s3) subdomains
- ports
80and443available on the host - exact EnvSync release version to deploy
Recommended public hosts:
app.<root-domain>for the dashboardapi.<root-domain>for the API (product and Enterprise manage at/api/v1/manage/...)auth.<root-domain>for Atriumobs.<root-domain>for ClickStack (if observability enabled)t.<root-domain>for first-party analytics (/ph→ PostHog,/obs→ OTLP)s3.<root-domain>for the S3-compatible APIconsole.s3.<root-domain>for the object storage console
There is no separate manage-api.<root-domain> service. Enterprise self-host uses the enterprise API image (envsync-api-enterprise) with manage routes on the same API host.
Self-host does not require a marketing landing host. Public signup is Hosted-only.
Product analytics (PostHog) is optional. If POSTHOG_KEY / VITE_POSTHOG_KEY are set, the API and dashboard send non-secret product events (creates, invites, SSO, KMS attach — never env/secret values). Set ENVSYNC_POSTHOG_DISABLED=true to turn this off.
Prepare the host:
npx @envsync-cloud/deploy preinstallCreate /etc/envsync/deploy.yaml:
npx @envsync-cloud/deploy setupBootstrap the managed infra:
npx @envsync-cloud/deploy bootstrapDeploy the pinned release:
npx @envsync-cloud/deploy deploySelf-host has no public signup and no dashboard “create organization”.
Create the first org with the operator CLI (setup token under /etc/envsync/setup.token):
# Interactive (TTY)
envsync-deploy org create --interactive
# Non-interactive
envsync-deploy org create \
--name "Acme" \
--email "admin@example.com" \
--password 'Str0ng!Pass'
# Status
envsync-deploy org status
envsync-deploy health --json # includes first_org.ready- OSS: at most one organization.
- Enterprise self-host: one org by default; further orgs only via
org createwhen license/ENVSYNC_MAX_ORGSallows (not via web). Useenvsync-deploy-enterprise.
Important facts:
setupwrites the desired self-host config (edition oss for this package).bootstrapis destructive and rebuilds the managed EnvSync infra.bootstrap/ deploy may prompt for the first org when a TTY is available.deployperforms the release rollout.- running
envsync-deploywith no subcommand shows the current status and the recommended next step.
Upgrade to the running deploy package version:
bunx @envsync-cloud/deploy@0.20.0 upgradeUpgrade to an exact target:
bunx @envsync-cloud/deploy@0.20.0 upgrade 0.20.0Blue/green behavior:
- the inactive API slot is updated first
- traffic promotes only after the candidate slot is ready
- the previous API slot stays available for rollback
Manual slot control:
envsync-deploy promote
envsync-deploy rollbackCreate an encrypted backup. The default is age. The archive is envsync-backup-<time>.tar.gz.age. The identity file is written beside it as envsync-backup-<time>.identity and is not inside the archive. Keep that identity file with your other operator secrets. The file mode is 0600.
envsync-deploy backupbackup.encrypted defaults to true. A plaintext .tar.gz is refused. To write one anyway, set backup.encrypted: false in the deploy config and pass the insecure flag:
envsync-deploy backup --insecure-unencryptedA normal backup also encrypts any older envsync-backup-*.tar.gz files in the output directory and deletes the plaintext copies. Each of those gets its own .identity file beside the new .age archive.
Restore an encrypted archive. If the identity file is next to the archive, you can omit --identity.
envsync-deploy restore /path/to/envsync-backup.tar.gz.age --identity /path/to/envsync-backup.identityRestore and start services immediately:
envsync-deploy restore /path/to/envsync-backup.tar.gz.age --deployHuman-friendly health view:
envsync-deploy healthMachine-readable health:
envsync-deploy health --jsonThe health output shows:
- bootstrap state
- active and rollback API slots
- service health for API, web, and observability
- first organization readiness
- public URLs
Before publishing deploy package changes from the monorepo:
bun run selfhost:smoke:oss- packages/deploy — public OSS CLI (
@envsync-cloud/deploy) - packages/deploy-cli — enterprise sources published as
@envsync-cloud/deploy-enterprise - docker/atrium — Atrium config, clients, and branding
Enterprise self-host requires a valid license install (entitlement JWT and/or certificate bundle under the paths configured by deploy). Verify with the enterprise deploy CLI and license controls in the dashboard (/organisation/license). Hosted SaaS uses platform billing instead of customer-side license files.