Deployment

API-only and separate Studio hosting

Disable built-in Studio serving and keep a separately hosted Studio on the same public origin as the API.

Set POSTDOT_WEB_ENABLED=false to run Postdot without serving Studio files. The API, authentication, scheduler, publication worker and storage continue running. The standard image keeps serving Studio by default.

Choose this option for API automation or to serve the static Studio through your own web server. Separating files does not remove the Postdot backend or change its storage and instance limits.

For a Cloudflare deployment, use the static Studio and protected Worker proxy recipe, including its local qualification and hosted acceptance checklist.

Run without Studio files

Add this setting to the deployment environment, or to the .env used by the repository's Compose configuration:

POSTDOT_WEB_ENABLED=false
BETTER_AUTH_URL=https://postdot.example.com
POSTDOT_WEB_ORIGIN=https://postdot.example.com

Restart Postdot. Requests to /dashboard on the backend now return 404; /health, /ready, /openapi/json and authenticated API routes remain available. The server does not require an index.html in POSTDOT_WEB_ASSETS_DIR while this flag is false. With the default true, a missing Studio build still prevents startup.

Disabling files does not make the API private or remove human-session endpoints. Keep HTTPS, authentication and your existing network access rules.

Provision an API key without Studio

On a fresh production instance (NODE_ENV=production), first-run bootstrap defaults to token_required mode so public signup never opens automatically. Postdot generates a one-time bootstrap token at <dataDir>/bootstrap-token unless you supply POSTDOT_BOOTSTRAP_TOKEN, POSTDOT_BOOTSTRAP_TOKEN_FILE, or POSTDOT_BOOTSTRAP_TOKEN_HASH (or explicitly opt into POSTDOT_BOOTSTRAP_MODE=open).

You can claim the instance and mint the initial API key atomically without opening Studio or signing into a cookie jar:

  1. Online token-gated bootstrap (@postdot/cli or POST /api/instance/bootstrap): Keep the server running and pass the one-time token via --bootstrap-token-file (or X-Postdot-Bootstrap-Token / Authorization: Bearer) alongside --issue-api-key:

    postdot --url https://postdot.example.com instance bootstrap \
      --name "Administrator" \
      --email "admin@example.com" \
      --password-file /run/secrets/admin-password \
      --bootstrap-token-file /data/bootstrap-token \
      --issue-api-key \
      --api-key-name "Bootstrap admin key" \
      --json
  2. Offline provisioning with key issuance: Stop Postdot and run offline provisioning with --issue-api-key and --api-key-output <path> to write the minted key directly to a private file with restricted permissions:

    bun /app/postdot.js account bootstrap \
      --database /data/postdot.sqlite \
      --input /run/secrets/bootstrap.json \
      --issue-api-key \
      --api-key-name "Bootstrap admin key" \
      --api-key-output /run/secrets/initial-api-key.json

For an already claimed instance without Studio, you can also sign in through a private curl cookie jar in a umask 077 directory to mint an initial key:

umask 077
curl --fail --silent --show-error \
  --cookie-jar session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data-binary @credentials.json \
  --output session.json \
  https://postdot.example.com/api/auth/sign-in/email

curl --fail --silent --show-error \
  --cookie session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data-binary @key-request.json \
  --output created-key.json \
  https://postdot.example.com/api/api-keys

curl --fail --silent --show-error \
  --cookie session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data '{}' --output /dev/null \
  https://postdot.example.com/api/auth/sign-out

The minted token is returned once. Transfer it to your tool's secret storage, then delete any temporary credentials or response files. Once provisioned, an API key granted api_key:manage, workspace:manage, project:access_manage, or instance:admin can administer keys, members, invitations, workspaces, and settings over the API, CLI, or MCP without a browser session. See authentication for the remaining session-only operations (such as interactive provider OAuth callbacks and password changes) and the CLI for administrative commands.

Without a Studio destination, invitation pages, notification links and interactive publisher OAuth return pages have no interface to display. Use non-OAuth provider connections or API-key workflows where available, and offline account recovery when an administrator password is lost.

Serve Studio separately

Use Studio from the same release and source revision as your API. Releases made with the updated publication workflow attach postdot-studio-<version>.tar.gz and include it in SHA256SUMS. Earlier releases, including 0.1.0-alpha.7, do not have that archive; use their matching source when an asset is absent.

Use a release archive

Read the installed API's GET /api/version or use the release identification command. In a new empty directory on Linux, replace the version below with that exact release, without the v prefix:

POSTDOT_RELEASE_VERSION='replace-with-api-version'
curl --fail --location --remote-name \
  "https://github.com/postdot/postdot/releases/download/v${POSTDOT_RELEASE_VERSION}/SHA256SUMS"
curl --fail --location --remote-name \
  "https://github.com/postdot/postdot/releases/download/v${POSTDOT_RELEASE_VERSION}/postdot-studio-${POSTDOT_RELEASE_VERSION}.tar.gz"
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf "postdot-studio-${POSTDOT_RELEASE_VERSION}.tar.gz"

The checksum command verifies the downloaded archive while skipping installation files you did not download. Stop if verification fails. Keep the release download and checksum from the same trusted source; checksums alone do not authenticate an unknown archive.

The extracted postdot-studio-<version>/public directory contains the image's exact Studio files. Keep its sibling license, attribution and licenses/ files with the distribution. studio-release.json records the version, full source revision, immutable image reference and per-file SHA-256 values; compare its version and revision with your API before deploying. Its sibling release.json is the identity read from the image. Static browser files are architecture-independent; the archive is extracted from the Linux AMD64 member of that same image release.

Point your static server at the extracted public directory, using the routing rules below. Preserve the unmodified release as the rollback input. Keep previous hashed assets available in your serving directory for already open tabs during the update; verify an archive before adding retained assets to its serving copy.

Build from source

If your release has no archive, build from its exact source revision and copy the contents of apps/web/dist to your static server. Use the repository's pinned Bun version and frozen dependencies:

bun install --frozen-lockfile
bun run --cwd apps/web build

Source builds record the public POSTDOT_VERSION and POSTDOT_REVISION build variables in their JavaScript and studio-build.json. Supply the version and full 40-character commit of the Studio source you are actually building if you want installation diagnostics to compare it with the API. Both unset means an unversioned build; a missing field keeps the comparison incomplete. Invalid nonempty values fail the build. Do not apply a backend's labels to unrelated Studio files or expect runtime environment changes to relabel an already built Studio.

The release image passes those build variables automatically. Its archive retains the same identity. Diagnostics use the identity embedded in the loaded JavaScript, so replacing studio-build.json alone cannot update an open tab's reported build.

Publish the generated files as one release directory; preserve old hashed assets for already open tabs during updates. Keep third-party notices and licenses with redistributed files.

Use one public HTTPS origin, for example https://postdot.example.com:

RequestsDestination
Studio pages, JavaScript, styles and local datasetsStatic Studio files
/api and /api/*Postdot backend, including authentication, uploads and SSE
/oauth and /oauth/*Postdot backend, including public provider metadata

Set both BETTER_AUTH_URL and POSTDOT_WEB_ORIGIN to that public origin. Preserve the path and query string through the proxy. Provider callbacks must arrive on that origin so the browser sends the session cookie; register the matching public callback URLs with each provider. Keep the backend upstream address in deployment configuration. Do not expose it as a user-controlled forwarding parameter.

The proxy handles passwords, session cookies and private media. Use a trusted operator-controlled deployment, preserve Origin and Set-Cookie, sanitize forwarded headers, and bypass caching for every API/OAuth response. Retain signed-media expiry checks. Forward SSE bodies as streams, allow upload bodies up to your configured media limit, and stop upstream streams when clients disconnect.

Configure trusted proxy addresses with POSTDOT_TRUSTED_PROXIES. Postdot verifies the connected peer before using the forwarded chain for authentication quotas and session IP tracking. Forwarding headers alone does not establish that trust. Quotas remain local to each API process; qualify shared ingress limits separately for multiple replicas.

Nginx routing example

This example assumes TLS certificates already exist and the backend listens on 127.0.0.1:3000. Install the matching Studio build at /srv/postdot/studio. Use the reverse-proxy guide for TLS and network setup.

server {
    listen 443 ssl;
    server_name postdot.example.com;
    ssl_certificate /etc/letsencrypt/live/postdot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/postdot.example.com/privkey.pem;
    root /srv/postdot/studio;
    client_max_body_size 100m;
    add_header X-Robots-Tag "noindex, nofollow" always;

    location ~ ^/(api|oauth)(/|$) {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_cache off;
        proxy_intercept_errors off;
        proxy_read_timeout 300s;
        add_header Cache-Control "no-store" always;
        add_header X-Robots-Tag "noindex, nofollow" always;
    }

    location = /robots.txt {
        return 200 "User-agent: *\nDisallow: /\n";
    }
    location ~ \.[^/]+$ {
        try_files $uri =404;
    }
    location / {
        try_files $uri /index.html;
        add_header Cache-Control "no-cache" always;
        add_header X-Robots-Tag "noindex, nofollow" always;
    }
}

API errors retain their status and body; an unknown API path must never receive Studio's index.html. Keep backend probes, OpenAPI, MCP and metrics reachable according to your operator policy; this example routes only browser application traffic. Match the upload limit to POSTDOT_MEDIA_MAX_OBJECT_BYTES if you raise it.

The repository acceptance journey exercises a separately served production build against an asset-free production API through a local HTTPS proxy. It does not qualify a particular Nginx version or hosted CDN. Check cookies, private media, uploads and SSE reconnection with your ingress configuration. Cloud-hosted proxy timeouts, body limits and cache behavior require their own qualification before using Cloudflare or Vercel as that ingress.

To return to integrated serving, restore POSTDOT_WEB_ENABLED=true, provide the matching assets and route application traffic to Postdot. Preserve the public origin and release pairing to avoid changing callback registrations or session scope during the move.

Was this page helpful?

On this page