Deploy a NetScript workspace

Goal: take the workspace you scaffolded with netscript init and run it somewhere other than your laptop — a container host, a VM, or a managed platform — with clear expectations about what the scaffold wires for you and what you still own.

This is a task recipe, not a one-click button. NetScript is in alpha, and the scaffold is deliberately minimal about deployment: it gives you a single declarative description of every process (appsettings.json), runnable Deno entrypoints with explicit permissions, and the Aspire AppHost that orchestrates them locally. It does not generate a Dockerfile, a docker-compose.yml, or a cloud target for you. Those are yours to add, and this page shows you exactly which verified facts to build them from.

Before you start

You need a working, type-checked workspace and a clear idea of where it is going. If you have not built one yet, start with Quickstart and the Storefront tutorial. Then confirm the workspace is healthy locally before you try to move it:

deno task check    # type-check apps, services, contracts
deno task lint
deno task test

For the orchestration model that underpins everything below — why the AppHost lives in its own aspire/ folder, and how it provisions Postgres and Redis — read the Aspire explanation alongside this recipe.

The mental model: three layers

A NetScript deployment is three layers, and you choose how much of each you keep in production:

Step 1 — Know your deployable units (appsettings.json)

appsettings.json is the single source of truth for what runs. The CLI writes it during netscript init and updates it as you netscript plugin add. Every Aspire resource — and every process you would deploy by hand — is described there. From a workspace with the four first-party plugins installed, the graph looks like this:

Each entry carries the exact information a deploy needs: Runtime, Port, Entrypoint, Workdir, RequiresDb/RequiresKv, the Deno Permissions array, the concurrency env var, and PluginReferences (the wiring order). When you containerize or write systemd units, copy these values verbatim — do not guess them.

Step 2 — Build and validate a release artifact

There is no opinionated build step that produces a single bundle — each Deno process runs from source. Your "build" is therefore: cache dependencies, type-check, and (optionally) pre-generate the database client and plugin registries so the container does not do it at boot.

# From the workspace root — prove the graph is healthy before you ship it.
deno task check
deno task lint
deno task test

# Warm the module cache so production start-up does no network fetch.
# Cache each deployable entrypoint you intend to run.
deno cache services/users/src/main.ts
deno cache plugins/workers/services/src/main.ts
deno cache plugins/sagas/services/src/main.ts
deno cache plugins/triggers/services/src/main.ts

# Requires Aspire (and therefore Postgres) up first — see the DB callout below.
# Bake the Prisma client + plugin registries into the artifact so boot is deterministic.
netscript db generate
netscript generate plugins

Step 3 — Provision backing services

In production you do not run Postgres and Redis as throwaway Aspire containers. You provision them as durable, managed resources and hand their connection details to NetScript through environment variables. NetScript reads the database URL from POSTGRES_URI (falling back to DATABASE_URL) and normalizes engine-specific connection strings to a URL — this is handled in database/postgres/prisma.config.ts.

Step 4 — Choose an orchestration path

This is the real fork in the road. Pick based on whether your target understands Aspire.

# The AppHost is a TypeScript/Node project under aspire/ (apphost.mts).
# Locally it provisions Postgres + Redis and wires every process.
cd aspire
aspire restore   # one-time: restore the TS AppHost SDK
aspire start       # boots the full graph; dashboard at http://localhost:18888

# Aspire 13.x can also publish a deployment manifest from the same AppHost
# (e.g. `aspire publish`). The scaffold wires the AppHost graph; it does NOT
# pre-select a cloud target for you — you point publish at your platform.

# Scaffold without the orchestration layer, then run processes yourself.
netscript init my-app --no-aspire

# You now own provisioning Postgres + a cache, and starting each process.
# Bring-your-own-supervisor: systemd, a container per process, or a PaaS.
# Start the Fresh app directly during dev:
deno task --cwd apps/dashboard dev

Step 5 — Run a process by hand (the bare-metal primitive)

Under every option above, the atomic unit is the same: one Deno process started from an entrypoint with the exact permission set from appsettings.json. This is what a container CMD, a systemd ExecStart, or a PaaS start command ultimately becomes. For the workers API (:8091), it is:

# Run from the workspace root. Flags and entrypoint come straight from appsettings.json.
PORT=8091 \
deno run \
  --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run \
  plugins/workers/services/src/main.ts

The corresponding background processor (which actually executes jobs) runs its own entrypoint:

# Workers + sagas background processors share bin/combined.ts; triggers uses its own.
WORKERS_CONCURRENCY=2 \
deno run \
  --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run \
  workers/bin/combined.ts

Map this pattern across every enabled resource and you have a complete, container-free deployment. To containerize, each process becomes one image whose CMD is the matching deno run line; orchestrate them with compose or your platform of choice, honoring the PluginReferences start order (streams → workers → sagas/triggers, plus auth-api when present).

Step 6 — Verify the deployment

Once your processes are up against real backing services, hit the health endpoints to confirm the graph is wired. These are the exact routes the local runtime exposes (substitute your production host):

# Smoke a deployed graph (replace localhost with your host).
curl -fsS http://localhost:8091/health
curl -fsS http://localhost:8092/health/live
curl -fsS http://localhost:8093/health
curl -fsS "http://localhost:8091/api/v1/workers/jobs"

If every health endpoint returns and /api/v1/workers/jobs lists your jobs, the processes are running with their permissions, reaching Postgres/KV, and discovering their registries — the deployment is live.

Where to go next

For the full generated API of each deployable unit, see the reference: workers, sagas, triggers, and streams. For every CLI command grouped by workflow, see the CLI reference.