Deployment

Run deploy from the app directory.

nstack deploy

The deploy flow discovers Encore resources, renders deploy files, provisions the Dokploy target, rebuilds generated client code, deploys backend and frontend services, and verifies the published URL.

Targets

Targets represent Dokploy environments such as production or staging.

nstack target create staging --domain staging.example.com

Use targets when the same app needs separate domains, secrets, resource instances, or deployment history.

Servers and networks

On a Dokploy instance with remote servers, select the deployment server:

nstack configure --server-id <server-id>

Use --server-id local for the Dokploy manager. Existing apps keep their server; changing servers requires migrating the app and its data.

nstack reuses an existing app network. For new apps, it inspects Docker networks on the selected server and reserves a free /24 from 10.240.0.0/12 before deploying. Concurrent allocation conflicts trigger a retry. Docker assigns container IPs, and services communicate through DNS names. The private network remains separate from Dokploy's ingress network.

If your host or VPN routes use that range, set deploy.networkSubnet to an unused private CIDR in nstack.config.mjs. Docker network discovery does not include host routes. Existing networks are never resized automatically. Reserved networks remain after app removal; remove them in Dokploy when no containers use them.

Object storage

Encore buckets use RustFS and its rc client with a dedicated rustfs_data volume. New deployments use NSTACK_RUSTFS_ACCESS_KEY and NSTACK_RUSTFS_SECRET_KEY. Pulling or deploying an older app imports its NSTACK_MINIO_* credentials without rotating them.

For an existing MinIO service, run:

nstack deploy --migrate-storage --docker-host ssh://user@server --env prod

Use Docker access to the selected Dokploy server. nstack checks the container identity before stopping writers. The migration stops the app, clones its single named /data volume, and verifies every object version, content hash, delete marker, object metadata, bucket versioning setting, and public policy through RustFS before deploying. It retains the original MinIO volume. A failed verification removes only the new clone and restarts the original containers. A verified migration can be retried with the same command after a deploy failure; the original service stays stopped until cutover. Do not restart MinIO after RustFS accepts writes without reconciling those writes first.

RustFS supports MinIO disk-format import, but migration is one-way. Distributed drive sets, encryption integrations, and external identity or notification services require a separate migration. Unsupported data fails verification before cutover. The command needs downtime and enough disk space for a copy.

Generated deploy output

During deploy, nstack renders the resource plan and Dokploy service definitions from source. Treat those files as CLI output and change the app code or target config when the deploy shape needs to change.

Generated Compose keeps infrastructure credentials as environment references. After declaring a new database, cache, or object storage bucket, run nstack deploy once before relying on automatic push deployment.

When an initial push creates a Gitea or Forgejo repository, nstack explicitly requests private visibility.

Experimental rolling deploys

Dokploy's regular Compose deployment is the default. To test nstack's health-gated rollout, set deploy.zeroDowntime to true in nstack.config.mjs, then run nstack deploy.

The experimental rollout starts replacement backend and frontend containers and waits for their health checks before removing the current containers. Keep database migrations compatible with both backend versions during the handoff. Run nstack deploy again after disabling the option so automatic provider-backed pushes return to Dokploy's regular Compose command.

After deploy

Check status and follow logs from the same CLI.

nstack status
nstack logs --follow