Docker Reference

Image Contents

The ghcr.io/archmaxai/archmax Docker image bundles the application components needed to run archmax:

Component	Description
API server	Hono HTTP server on port 3000 (internal)
BullMQ worker	Background job processor for AI agent tasks
Frontend SPA	React admin UI served as static files
nginx	Reverse proxy on port 8080; routes `/api/` and `/mcp/` to the API, serves SPA for everything else
MongoDB	Embedded `mongod`; starts automatically when `MONGODB_URI` is not set
Redis	Embedded `redis-server`; starts automatically when `REDIS_URL` is not set

Base image: node:24-slim (Debian Bookworm).

Exposed Ports

Port	Protocol	Description
`8080`	HTTP	nginx reverse proxy (the only port you need to expose)

Internal services (API on 3000, MongoDB on 27017, Redis on 6379) bind to 127.0.0.1 and are not accessible from outside the container.

Environment Variables

Required

Variable	Description
`BETTER_AUTH_SECRET`	Session encryption secret. Min 32 characters. Generate with `openssl rand -base64 32`. Save this value and reuse it across container restarts and upgrades. Changing or losing it invalidates all existing sessions and authentication data.
`UI_PASSWORD`	Initial admin password. Used to seed the admin account on first run.

Optional Services

Variable	Default	Docker Behavior
`MONGODB_URI`	(embedded)	Optional. When omitted, the entrypoint starts an embedded `mongod` at `mongodb://127.0.0.1:27017/archmax` with persistent data at `/data/mongodb`. Set this to use an external MongoDB instance.
`REDIS_URL`	(embedded)	Optional. When omitted, the entrypoint starts an embedded `redis-server` at `redis://127.0.0.1:6379` with ephemeral data at `/tmp/redis`. Set this to use an external Redis instance.

Server

Variable	Default	Description
`APP_BASE_URL`	-	Public URL of this instance (e.g. `https://archmax.example.com`). Set this when running behind a reverse proxy or on a cloud host. Automatically configures CORS and auth origins.
`PORT`	`3000`	Internal API server port. Normally not changed; nginx proxies port 8080 to this.
`CORS_ORIGINS`	(derived)	Comma-separated allowed origins. Defaults to `APP_BASE_URL` when set. Override only if you need additional origins.
`AUTH_BASE_URL`	(derived)	Auth callback URL. Defaults to `APP_BASE_URL` when set, otherwise `http://localhost:PORT`.

Admin Credentials

Variable	Default	Description
`UI_USERNAME`	`admin`	Initial admin username.
`UI_PASSWORD`	-	Required. Initial admin password.

Data

Variable	Default	Description
`ARCHMAX_DATA_DIR`	`/data`	Root data directory for all persistent application data. Normally not changed in Docker.

AI Agent

Variable	Default	Description
`AGENT_API_BASE_URL`	`https://openrouter.ai/api/v1`	OpenAI-compatible API endpoint. Change this when using a provider other than OpenRouter.
`AGENT_API_KEY`	-	Required for agent features. API key for your chosen provider.
`AGENT_MODEL`	`anthropic/claude-sonnet-4`	Model identifier (must match your provider’s naming convention).
`AGENT_TITLE_MODEL`	`anthropic/claude-haiku-4-5-20250929`	Cheap/fast model for conversation title generation.

Supported providers: OpenRouter (default), OpenAI, Azure OpenAI, Ollama, or any OpenAI-compatible endpoint.

Worker

Variable	Default	Description
`WORKER_CONCURRENCY`	`5`	Number of concurrent agent jobs the worker processes.

MCP Server

Variable	Default	Description
`MCP_RATE_LIMIT_MAX`	`120`	Max MCP requests per IP per 60-second window.

Testing

Variable	Default	Description
`TEST_AGENT_MAX_ITERATIONS`	`100`	Max tool call iterations for playground and batch test agents.

Security

Variable	Default	Description
`ENCRYPTION_KEY`	-	Encrypts database connection passwords and API keys at rest (AES-256-GCM). Generate with `openssl rand -base64 32`.

GitHub Integration (Optional)

Variable	Default	Description
`GITHUB_CLIENT_ID`	-	GitHub OAuth app client ID.
`GITHUB_CLIENT_SECRET`	-	GitHub OAuth app client secret.

Volumes

Container Path	Contents	Persistent?	Notes
`/data/projects/`	Semantic model YAML files	Yes	Core application data
`/data/mongodb/`	Embedded MongoDB data files	Yes	Only used when `MONGODB_URI` is not set
`/data/.duckdb/`	DuckDB extension cache	Yes	Created when DuckDB loads extensions
`/tmp/redis/`	Embedded Redis data	No	Ephemeral by design; queue data is transient

Recommended Volume Mount

-v ~/.archmax:/data

This bind mount maps the container’s data directory to ~/.archmax on the host, including project files (semantic model YAMLs), the DuckDB extension cache (.duckdb/), and embedded MongoDB data. When using Docker Compose with an external MongoDB service, the mongodb/ directory is unused and MongoDB data is managed by the Compose mongo service volume.

Entrypoint Behavior

The container entrypoint (/entrypoint.sh) follows this startup sequence:

1. Set ARCHMAX_DATA_DIR (default: /data)
2. If MONGODB_URI is not set:
   ├── Create $ARCHMAX_DATA_DIR/mongodb (if missing)
   ├── Start mongod (fork, bind 127.0.0.1, data at $ARCHMAX_DATA_DIR/mongodb)
   ├── Wait for readiness (ping loop, max ~10s)
   └── Export MONGODB_URI=mongodb://127.0.0.1:27017/archmax
3. If REDIS_URL is not set:
   ├── Create /tmp/redis (if missing)
   ├── Start redis-server (daemonize, bind 127.0.0.1)
   └── Export REDIS_URL=redis://127.0.0.1:6379
4. Start BullMQ worker (background)
5. Start API server on port 3000 (background)
6. Start nginx on port 8080 (foreground, PID 1)

Decision Matrix

`MONGODB_URI` set?	`REDIS_URL` set?	Embedded MongoDB	Embedded Redis
No	No	Started	Started
Yes	No	Skipped	Started
No	Yes	Started	Skipped
Yes	Yes	Skipped	Skipped

Health Checks

The API exposes a health endpoint you can use for Docker health checks or load balancer probes:

curl -f http://localhost:8080/api/health

Docker HEALTHCHECK example:

HEALTHCHECK --interval=30s --timeout=5s --start-period=30s \
  CMD curl -f http://localhost:8080/api/health || exit 1

Or in Docker Compose:

services:
  archmax:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 5s
      start_period: 30s

CI Verification

After the Docker image is built in CI, Playwright end-to-end tests run against the image (started via docker-compose.ci.yml with local MongoDB and Redis) to validate login, navigation, and health before merge.

Resource Requirements

Deployment	Min RAM	Min Disk	Recommended CPU
Standalone (embedded MongoDB + Redis)	512 MB	2 GB	1 vCPU
Standalone (external MongoDB)	256 MB	1 GB	1 vCPU
Docker Compose (small team)	1 GB total	5 GB	1 vCPU
Docker Compose (production)	2 GB total	10 GB	2 vCPU

The embedded MongoDB adds ~200 MB RAM overhead. When using external MongoDB via MONGODB_URI, the container has a smaller memory footprint. The AI agent runs remotely via API calls and does not consume local GPU/CPU.

Examples

Docker Compose (Recommended)

git clone https://github.com/archmaxai/archmax.git
cd archmax
cp .env.example .env
# Edit .env with your values
docker compose up -d

See the docker-compose.yml in the repository root for the full configuration.

Standalone (Embedded MongoDB + Redis)

docker run -d \
  --name archmax \
  -p 8080:8080 \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=changeme \
  -e AGENT_API_KEY=your-api-key \
  -v ~/.archmax:/data \
  ghcr.io/archmaxai/archmax:latest

Standalone with External MongoDB

docker run -d \
  --name archmax \
  -p 8080:8080 \
  -e MONGODB_URI=mongodb://mongo.example.com:27017/archmax \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=changeme \
  -e AGENT_API_KEY=your-api-key \
  -v ~/.archmax:/data \
  ghcr.io/archmaxai/archmax:latest

Behind a Reverse Proxy

When archmax is accessible through a custom domain or reverse proxy, set APP_BASE_URL to the public URL:

docker run -d \
  --name archmax \
  -p 8080:8080 \
  -e APP_BASE_URL=https://archmax.example.com \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=changeme \
  -e AGENT_API_KEY=your-api-key \
  -v ~/.archmax:/data \
  ghcr.io/archmaxai/archmax:latest

With Custom AI Provider

docker run -d \
  --name archmax \
  -p 8080:8080 \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=changeme \
  -e AGENT_API_KEY=sk-your-openai-key \
  -e AGENT_API_BASE_URL=https://api.openai.com/v1 \
  -e AGENT_MODEL=gpt-4o \
  -v ~/.archmax:/data \
  ghcr.io/archmaxai/archmax:latest

Troubleshooting

Container exits immediately

Check the logs for the startup error:

docker logs archmax

Common causes:

Missing required environment variable (BETTER_AUTH_SECRET or UI_PASSWORD)
BETTER_AUTH_SECRET is shorter than 32 characters
Embedded MongoDB failed to start (check the logs for mongod startup errors)

Cannot connect to MongoDB

If using embedded MongoDB, check the mongod log:

docker exec -it archmax cat /var/log/mongod.log

If using an external MongoDB, verify the connection string from inside the container:

docker exec -it archmax node -e "
  const { MongoClient } = require('mongodb');
  MongoClient.connect(process.env.MONGODB_URI).then(() => console.log('OK')).catch(e => console.error(e.message));
"

Common causes:

Network/firewall blocking the connection
DNS resolution failure (use IP address or ensure Docker DNS resolves the hostname)
Missing ?authSource=admin for authenticated MongoDB instances
When using Docker Compose, ensure the mongo service is healthy before archmax starts (depends_on)
Embedded MongoDB fails on corrupted data; delete the /data/mongodb directory and restart

Port 8080 already in use

Map to a different host port:

docker run -d -p 9090:8080 ... ghcr.io/archmaxai/archmax:latest

Volume permission errors

If running as a non-root user or on SELinux-enabled hosts, add the :Z flag:

-v ~/.archmax:/data:Z