Local Compiler

Run the Quickback compiler locally using Docker. This is a fully supported compiler mode, not a reduced fallback: it uses the exact same Docker image as the hosted compiler and produces the same backend, migrations, SDKs, and SPA builds while keeping compile source on the local machine.

Prerequisites

Docker Desktop installed and running
Quickback monorepo cloned locally

Quick Start

From the monorepo root:

cd apps/compiler-local && bash dev.sh

This will:

Ensure Docker Desktop is running
Stop any existing compiler container
Build the Docker image from apps/compiler/Dockerfile
Start it in explicit local mode, published only on 127.0.0.1:3000

Custom Port

bash dev.sh 3001

Compiling a Project

Point the CLI to your local compiler:

QUICKBACK_API_URL=http://localhost:3000 quickback build

Or export it for the session:

export QUICKBACK_API_URL=http://localhost:3000
quickback build

The supported launcher does not require quickback login. It opts the compiler into local mode and binds Docker's host port to loopback, so the unauthenticated compile endpoint is not exposed to the LAN. The CLI skips its login prompt only when QUICKBACK_API_URL has the exact hostname localhost, 127.0.0.1, or ::1; longer hostnames and URLs that merely contain those strings still use hosted authentication.

Manual Build & Run

You can also build and run the Docker image directly from the monorepo root:

# Build
docker build -t quickback-compiler -f apps/compiler/Dockerfile .

# Run with the same security boundary as the supported launcher
docker run --rm \
  -e QUICKBACK_COMPILER_MODE=local \
  -p 127.0.0.1:3000:3000 \
  quickback-compiler

QUICKBACK_COMPILER_MODE is fail-closed: only the exact value local bypasses compile authentication. If the variable is absent or misspelled, the compiler uses hosted authentication. Never publish a local-mode container on 0.0.0.0 or a non-loopback interface.

Verify

Check the compiler is running:

curl http://localhost:3000/health

How It Works

The Docker image includes:

Pre-installed dependencies for compiled projects (/deps/node_modules)
Generic prebuilt CMS and Account SPA bundles (/spa-prebuilt/cms/, /spa-prebuilt/account/), built once at image build

When compiling a project with cms: true or account: true, the compiler copies those prebuilt bundles into the project's src/apps/ — it never runs Vite per compile. The generated worker injects the per-project values (API URLs, feature flags) into every served SPA shell as window.__QUICKBACK_RUNTIME, and the SPAs read that runtime blob, so one generic bundle serves every project.

Security boundary

Loopback only. Local mode skips authentication, so the launcher publishes the port on 127.0.0.1 only.
No browser-driven compiles. In local mode, a request carrying an Origin header whose hostname is not localhost, 127.0.0.1, or [::1] gets 403 — checked before CORS, so a web page you visit cannot POST a compile to your machine. The CLI and curl send no Origin and are unaffected.
Unprivileged user. The server runs as the image's bun user (uid 1000). /app, /deps, and /spa-prebuilt are root-owned and not writable by it, and each compile works in its own 0700 directory under /tmp/quickback, so code that runs during one compile cannot plant files a later compile loads.

Deploying to Cloud

After making changes to the compiler, deploy to compiler.quickback.dev:

cd apps/compiler-cloud && bash deploy.sh

Troubleshooting

Image dependency or startup check fails

The Docker build installs the compiler's dependencies with a frozen lockfile, then starts the compiler and checks /health. A missing startup dependency or startup crash therefore fails the image build before deployment.

Every package imported by compiler code at runtime must be declared in apps/compiler/package.json under dependencies. A package available through another workspace's install is not necessarily available in the image. Keep apps/compiler/bun.lock in sync with the Dockerfile's isolated workspace (apps/compiler/package.json plus packages/deploy-contract); do not bypass a frozen-lockfile failure with an unlocked install. The compiler's compiler-image-imports.test.ts check also enforces this import boundary during pnpm verify. That command also builds Quickback's API and marketing site, so you can catch their TypeScript and CSS build failures before triggering a deployment. CI runs the same build checks.

Container not starting

docker logs quickback-compiler-local

Port already in use

# Find what's using the port
lsof -i :3000

# Use a different port
bash dev.sh 3001

Docker out of disk space

docker system prune -af

SPA asset warnings

Compiles never build the SPAs — the Docker image carries generic prebuilt CMS/Account bundles (built once, at image build) that a compile copies into src/apps/. A "prebuilt … SPA assets not found" warning means the image was built without the spa-prebuilt stage completing; rebuild it with bash dev.sh.

SPA dependency manifests (apps/compiler/deps-spa-cms-package.json, deps-spa-account-package.json) are only consumed by that image-build stage — if one is stale, the image build fails loudly, never a user compile.

On this page