nstack

nstack is a small release layer for Encore + Nuxt apps on Dokploy.

It keeps the app shape boring:

curl -fsSL https://nstack.tech/install.sh | bash
nstack init my-app
cd my-app
nstack setup
nstack deploy

Interactive nstack init can link Dokploy by picking a saved Dokploy instance or adding a new one, then asks you to pick an existing Git provider or add a manual Git source. It also asks which package manager to use for init; the Encore + Nuxt template currently supports pnpm and can remember it as the default for new projects. In CI, use nstack configure with flags or env vars for the same settings.

nstack init initializes a git repository when needed, creates the initial init commit, and sets origin when a repository URL is configured. If the app is created inside an existing worktree, nstack does not create a nested repo; it commits only the new app directory into the parent worktree. Before that commit, it runs pnpm install and pnpm approve-builds --all, so the lockfile and pnpm build approvals are part of the first commit. Source-backed deploys push the current repo before asking Dokploy to build it. When the backing Git repository needs to be created first, nstack treats a private repository as the default. On the initial Gitea or Forgejo push, nstack explicitly requests private visibility for push-to-create.

nstack deploy discovers Encore resources, renders Encore infra and Dokploy Compose, lets Dokploy build the production backend/frontend services from source, provisions Dokploy resources, creates Dokploy Domains/Traefik routes, deploys, verifies the public URL, and prints the result.

Dokploy's standard Compose deployment remains the default. An experimental health-gated rollout is available with deploy.zeroDowntime: true or NSTACK_ZERO_DOWNTIME=1. It starts replacement backend and frontend containers, waits for their health checks, then removes the previous containers. Run nstack deploy after changing this setting so Dokploy stores the selected deployment command for provider-backed pushes.

For automatic deploy-on-push, connect the matching Git provider in Dokploy first. nstack can configure Dokploy Compose source deployments for GitHub, GitLab, Bitbucket, and Gitea/Forgejo when Dokploy has that provider connected. Plain Git source mode is available for custom hosts, but provider-backed sources are the path that gives Dokploy native push webhooks. Provider-backed push deploys reuse infrastructure credentials prepared by nstack deploy. When code declares a new Postgres database, cache, or object storage bucket, run nstack deploy once before relying on push deployment. A push with missing infrastructure credentials stops instead of generating a predictable fallback. Provider-backed nstack deploy updates Compose and its private Dokploy environment before pushing, then waits for the push webhook deployment when that push occurs. If the pushed commit only changes files outside the provider watch paths, nstack deploy triggers Dokploy directly after the push instead of waiting for a webhook that the provider filters out.

Daily Commands

nstack setup    # install local tooling and dependencies
pnpm dev        # or: nstack dev
nstack devexec 'await apiJson("/status")'
pnpm check      # or: nstack check
nstack deploy
nstack status

Add runtime variables to .env directly or use nstack env set NAME. nstack dev, deploys, and nstack env run -- <command> load the same file. Use nstack logs --follow when a deploy is running. nstack update refreshes a git-installed nstack checkout. The CLI prints an update notice after normal commands when nstack.tech reports a newer version.

When Needed

nstack doctor
nstack target create staging --domain staging.example.com
nstack pull
nstack update
nstack backup
nstack rollback
nstack undeploy --yes
nstack cleanup
nstack open dashboard

The generated app keeps package scripts as aliases to the CLI. nstack setup installs project dependencies, bootstraps pnpm through Corepack when needed, installs the Encore CLI with the official installer when it is missing, and checks Docker only when declared Encore resources need it. pnpm dev calls nstack dev to run the Encore backend, Nuxt frontend, and generated client sync for HMR. On a fresh clone, pnpm dev and pnpm check reuse the CLI setup path before running. They stop with direct instructions when Docker is not running or cannot be accessed. pnpm check, pnpm build, and nstack deploy sync the Encore TypeScript client used by the Nuxt frontend. nstack client gen is available when you explicitly want to regenerate it. Client generation and deploy metadata use local Encore commands for Dokploy/nstack targets. The generated frontend includes Tailwind CSS 4 through its official Vite plugin, with shared theme tokens in frontend/app/assets/css/main.css. Nuxt Icon bundles the local icon set, and Nitro precompresses production assets with Brotli and gzip.

Generated templates intentionally keep backend/encore.app with an empty Encore app id. That is Encore's local-only mode and prevents local encore run or encore check from fetching Encore Cloud secrets. nstack uses nstack.config.mjs app.slug as the Dokploy/nstack identity instead.

When nstack dev detects an AI coding harness such as Codex or Claude Code, it refuses to start a long-running dev server by default. Agents should use nstack devexec '<js>' for one-shot checks against a temporary dev stack. Set NSTACK_AGENT_HARNESS=<name> for custom harnesses, or AI_ALLOW_DEVSERVER=1 when an agent truly needs an interactive dev server.

nstack cleanup asks for confirmation before using server-wide Dokploy cleanup endpoints for stopped containers, unused images, unused volumes, and Docker builder cache. Pass --yes only when that server-wide cleanup is intended.

nstack backup writes local snapshots under .nstack/backups/<target>/<year-month-day-hour-minute-second-utc>/. It stores Dokploy/app metadata, remote Dokploy Compose env values in compose.env, and data artifacts for stateful resources: Postgres dumps and Dokploy volume tars for Redis-compatible cache, RustFS object storage, NSQ Pub/Sub data, and custom named volumes declared with deploy.volumes.<name>.backup. A custom volume backup stops its declared service before Dokploy archives the volume, then restarts the service after the archive completes. Downloaded artifacts must match Dokploy's reported size and pass gzip or tar validation. Manifests record a SHA-256 for each verified artifact. Snapshot files preserve secrets for recovery and are written with private local permissions.

Source-controlled private services can be declared under deploy.services with either an image or a build, internal exposed ports, environment values, secret names, health checks, and named-volume mounts. They join only the private Compose network. Registry deployments build and push service images alongside the backend and frontend. Source-backed deployments render their Docker builds into Compose. A singleton service that mounts a named volume cannot use zeroDowntime: true.

Destructive deletion paths create a critical local backup first and refuse to continue if the backup cannot be completed. To intentionally delete without that guard, start the CLI with NSTACK_NO_BACKUPS_ON_DELETION=1. Data backups use Dokploy API-backed backup jobs and require a Dokploy backup destination; pass --backup-destination-id <id> or set NSTACK_BACKUP_DESTINATION_ID when more than one destination exists. If none exists, nstack aborts before destructive deletion.

For the detailed operator guide, see USING_NSTACK.md.

Dokploy Model

• Dokploy Projects and Environments own the app.
• Dokploy native Postgres and Redis-compatible Dragonfly cache resources are created when Encore declares SQL databases or cache clusters.
• Source-backed Git pushes use infrastructure credentials previously prepared by nstack deploy. Push deployment stops when a newly declared stateful resource has no prepared credential.
• A provider-backed nstack deploy that pushes a new commit relies on the push webhook deployment instead of triggering a second Compose deploy.
• Dokploy Compose builds and runs the backend/frontend services plus generated support services such as NSQ for Pub/Sub and RustFS for Encore object storage buckets. Public buckets add a small RustFS public-route adapter so Dokploy can keep /objects on the app domain while backend S3 traffic stays internal.
• Dokploy Domains/Traefik route / to Nuxt, /api to Encore, and /objects to the RustFS public adapter only when a public Encore bucket is declared.
• Dokploy Schedules run Encore cron jobs inside the backend container through a bundled private runner; cron endpoints should use api({ expose: false }, ...) so they cannot be triggered from public HTTP.
• .env is the app runtime environment inventory. nstack discovers Encore secrets and source references, routes matching variables into each service, and synchronizes every value to Dokploy during env push or deploy.

Large structured values can stay in a separate ignored file. Set an app value to @file:path, for example CHAIN_CONFIG=@file:chains.config.json. nstack reads the file for local commands and sends its contents to Dokploy while preserving the reference in .env.

There is no Caddy container and no manual Traefik label surface in generated Compose.

Cache resources are still addressed through Encore/Dokploy Redis connection settings, but new Dokploy cache resources use the official Dragonfly image by default. Existing Dokploy Redis resources are reused instead of replaced during normal code deploys.

Builds

The default build mode is compose: Dokploy receives a Compose file with build: sections, local image tags, and production Dockerfiles. That path does not need GHCR, Docker Hub, or any external image registry. The first deploy can pay for dependency downloads on the server; consecutive deploys reuse Docker and pnpm caches on the Dokploy host.

The Nuxt service is built with nuxt build and runs .output/server/index.mjs. It is not deployed with a dev server.

Registry/image mode is still available when needed:

nstack configure --build-mode registry --registry ghcr.io/acme/my-app
nstack build
nstack deploy --prebuilt

Files

• nstack.config.mjs is stable source config.
• .nstack/local.env stores local deploy settings with private permissions and is ignored.
• .env stores the app runtime environment with private permissions and is ignored.
• deploy/nstack/encore.infra.json is passed to the backend runtime.
• deploy/nstack/compose.dokploy.yaml is sent to Dokploy Compose.
• deploy/nstack/release.json records the build mode and release from nstack build.

For staging or other targets, pass --env <name>. nstack writes target-scoped files such as .nstack/local.staging.env, .env.staging, and .nstack/state.staging.json. If multiple local targets exist, interactive nstack deploy asks which environment to deploy; automation should pass --env <name>.

Monorepos are supported without repo-in-repo layouts. Run nstack from the app directory, for example nstack deploy --cwd apps/web; nstack scopes dirty Git checks, generated deploy artifact commits, and client generation to that app. For source-backed Dokploy deploys, subdirectory apps default to app-prefixed Compose source settings such as apps/web/deploy/nstack/compose.dokploy.yaml and watchPaths: ["apps/web/**"], so multiple nstack apps can share one repository without blocking each other.