Skip to main content

Dev Container

Open the monorepo in a fully configured development environment running inside a container. This is the fastest way to get started on any OS — the container ships with Node.js 24, Yarn 4, PostgreSQL (with pgvector), Redis, Meilisearch, and Claude Code CLI pre-installed and pre-configured.

Prerequisites​

  • Docker Desktop — Windows · macOS · Linux
    • Allocate at least 12 GB RAM in Docker Desktop → Settings → Resources (the build step is memory-intensive)
  • Visual Studio Code — download here
  • Dev Containers extension for VS Code — install here
Windows

Enable the WSL 2 backend in Docker Desktop (Settings → General → "Use the WSL 2 based engine") before opening the container.

Quick start​

git clone https://github.com/saasframe/saasframe.git
code saasframe

In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

Dev Containers: Reopen in Container

The first build takes 3–5 minutes. VS Code will reopen inside the container when it is ready.

Once inside the container, start the app:

yarn dev

Open http://localhost:3000/backend and sign in with the credentials printed by the initialisation step.

What is included​

ToolVersionNotes
Node.js24Pre-installed in the container
Yarn4Pre-installed via Corepack
PostgreSQL17 + pgvectorRuns as a container service
Redis7Runs as a container service
MeilisearchlatestRuns as a container service
Claude Code CLIlatestRun claude inside the container

All environment variables and service connection strings are pre-configured. You can start yarn dev immediately after the container finishes building.

Claude Code inside the container​

With a Max plan subscription (OAuth):

claude

Follow the OAuth login flow that opens in your browser.

With an API key:

Set ANTHROPIC_API_KEY in your host shell before opening the container:

# macOS / Linux
export ANTHROPIC_API_KEY=sk-ant-...
code saasframe

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
code saasframe

The Dev Container configuration picks up host environment variables automatically.

Custom environment variables​

Create apps/saasframe/.env.local inside the container (or on the host before opening). This file takes priority over .env, which is auto-generated:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
SF_DISABLE_VECTOR_SEARCH_AUTOINDEXING=false

Use SF_DISABLE_VECTOR_SEARCH_AUTOINDEXING=false only if you want automatic vector embedding jobs inside the container. The default example env keeps auto-indexing disabled until you opt in.

Rebuilding the container​

If you need a fresh start (e.g. after updating the devcontainer config or pulling major changes):

Open the Command Palette and run:

Dev Containers: Rebuild Container

This rebuilds the image from scratch. Your source files are mounted from the host and are not affected.

Troubleshooting​

Build fails or runs out of memory:

  • Increase Docker Desktop memory allocation to at least 12 GB (Settings → Resources → Memory).
  • After increasing, run "Rebuild Container".

Port conflicts: The container forwards ports 3000 (app), 4000 (splash), 5432 (Postgres), 6379 (Redis), and 7700 (Meilisearch). If any of these are occupied on the host, stop the local service or change the forwarded port in .devcontainer/devcontainer.json.

Changes not reflected: Source files are bind-mounted from the host, so changes appear immediately. If the app is not hot-reloading, restart yarn dev inside the container.