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
• Authenticated via quickback login

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. Run it on port 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

Authentication is always required. Run quickback login first if you haven't already.

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
docker run --rm -p 3000:3000 quickback-compiler

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.

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.