Local Compiler

Run the Quickback compiler locally using Docker. The local compiler uses the exact same Docker image as the cloud compiler, ensuring identical behavior — including SPA builds with correct environment variables.

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:

1. Ensure Docker Desktop is running
2. Stop any existing compiler container
3. Build the Docker image from apps/compiler/Dockerfile
4. 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 compile

Or export it for the session:

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

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)
• CMS and Account SPA source code (/spa/cms/, /spa/account/)
• Pre-installed SPA dependencies (/spa-deps/cms/, /spa-deps/account/)

When compiling a project with cms: true or account: true, the compiler builds the SPAs from source inside the container with the correct Vite environment variables (e.g., VITE_QUICKBACK_API_URL, VITE_QUICKBACK_ACCOUNT_URL). This ensures each project gets properly configured SPA assets without manual intervention.

The generated worker additionally injects the same per-project values into every served SPA shell as window.__QUICKBACK_RUNTIME, and the SPAs prefer that runtime blob over the baked env — so the served behavior is identical even with a generic (no-.env) SPA build.

Deploying to Cloud

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

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

Troubleshooting

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 build warnings

If you see SPA build warnings during compilation, ensure the SPA dependency files are up to date:

• apps/compiler/deps-spa-cms-package.json
• apps/compiler/deps-spa-account-package.json

These must include all dependencies from packages/cms/package.json and packages/account/package.json respectively.