Self-Hosting

Deployment Modes

archmax semantics supports two deployment modes. Choose the one that fits your needs:

	Docker Compose	Standalone Docker
Services	Separate containers for archmax semantics, MongoDB, and Redis	Single container with embedded MongoDB and Redis
Setup	Clone repo, configure .env, run docker compose up	Single docker run command
Backups	Each service has its own volume; easy to back up individually	Single /data bind mount captures project data, MongoDB (embedded), and DuckDB cache
Scaling	Can scale services independently; swap in managed MongoDB (Atlas, DocumentDB)	All-in-one; simpler but less flexible
Best for	Production deployments, teams, long-term use	Quick evaluation, demos, single-user setups

Docker Compose (Recommended)

The recommended way to run archmax semantics, with separate containers for the app, MongoDB, and Redis:

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

The included docker-compose.yml runs archmax semantics with dedicated MongoDB 8 and Redis 8 containers.

Standalone Docker

Run archmax semantics as a single container with embedded MongoDB and Redis, with no external dependencies:

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

MongoDB and Redis are embedded and start automatically. To use an external MongoDB, pass MONGODB_URI. To use an external Redis, pass REDIS_URL.

AGENT_API_KEY is required for the AI-powered Semantic Model Builder and Testing Playground. The default provider is OpenRouter; see the Configuration reference for alternative providers.

Caution

Save your BETTER_AUTH_SECRET value somewhere safe. If you lose it or change it on a restart, all existing sessions and authentication data become invalid. You will need to re-authenticate, and any Better Auth data tied to the old secret is lost.

Volumes & Data Persistence

archmax semantics stores persistent data inside the container at /data. You must mount this path to retain data across container restarts and upgrades.

Standalone Docker

The docker run examples use a bind mount that maps the container’s data directory to a host directory:

-v ~/.archmax:/data

This single mount captures everything: semantic model YAML files (projects/), embedded MongoDB data (mongodb/), and the DuckDB extension cache (.duckdb/). Without this mount, all data is lost when the container is removed.

Docker Compose

The included docker-compose.yml uses named Docker volumes:

Volume	Container Path	Contents
archmax-data	/data (archmax container)	Semantic model YAML files, DuckDB extension cache
mongo-data	/data/db (mongo container)	MongoDB database files

Named volumes are managed by Docker and persist automatically. To use host bind mounts instead (e.g. for easier access or backup), edit docker-compose.yml:

volumes:
  - ./data/semantics:/data   # instead of archmax-data:/data

Caution

Redis data is intentionally not persisted. The BullMQ queue is transient — incomplete jobs are retried on restart. If you need durable Redis data, configure an external Redis instance via REDIS_URL with its own persistence.

Railway / Custom Volume Mounts

When deploying to platforms like Railway that mount volumes at arbitrary paths (e.g. /data), set SEMANTICS_DATA_DIR to point inside the mount:

Variable	Value
SEMANTICS_DATA_DIR	/data/projects

The entrypoint automatically fixes ownership on the configured data directory before starting services, so root-owned volume mounts work out of the box.

Data Backup

archmax semantics stores two categories of persistent data:

Data	Location	Description
Project files	/data/projects/ (archmax container)	Semantic model YAML files
Embedded MongoDB	/data/mongodb/ (archmax container)	Database files (only when using embedded MongoDB)
DuckDB cache	/data/.duckdb/ (archmax container)	DuckDB extension cache
External Database	MongoDB service/instance	Projects, connections, conversations, test data (when using Compose or external MongoDB)

Tip

When using standalone Docker with embedded MongoDB, the single bind mount at /data captures all persistent state: project files, embedded MongoDB data, and the DuckDB extension cache. When using Docker Compose with external MongoDB, only project files (and DuckDB cache) live in the archmax semantics container volume.

Backing Up Project Files

1. Stop the container to ensure data consistency:

   docker compose stop archmax

2. Copy the volume to a backup location:

   docker run --rm \
     -v semantics_archmax-data:/data \
     -v $(pwd):/backup \
     alpine tar czf /backup/semantics-projects-$(date +%Y%m%d).tar.gz -C /data .

3. Restart:

   docker compose start archmax

Backing Up MongoDB (Docker Compose)

docker compose stop
docker run --rm -v semantics_mongo-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/semantics-mongo-$(date +%Y%m%d).tar.gz -C /data .
docker compose start

Tip

If you use a managed MongoDB service (Atlas, DocumentDB), rely on its built-in backup features instead.

Restoring

docker compose stop
# Restore project files
docker run --rm \
  -v semantics_archmax-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/semantics-projects-20260408.tar.gz -C /data"
# Restore MongoDB
docker run --rm \
  -v semantics_mongo-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/semantics-mongo-20260408.tar.gz -C /data"
docker compose start

Upgrading

1. Pull the latest images:

   docker compose pull

2. Back up your data (see above)

3. Recreate the containers:

   docker compose up -d

For standalone Docker:

docker pull ghcr.io/archmax-ai/semantics:latest
docker stop archmax && docker rm semantics   # use `archmax` if the container predates the rename
docker run -d --name semantics -p 8080:8080 \
  -e BETTER_AUTH_SECRET=your-existing-secret \
  -e ENCRYPTION_KEY=your-existing-key \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=your-password \
  -e AGENT_API_KEY=your-api-key \
  -v ~/.archmax:/data \
  ghcr.io/archmax-ai/semantics:latest

Caution

Upgrading from a release published as ghcr.io/archmaxai/archmax? See Upgrading from archmax — it is an image-name change only.

Keep your BETTER_AUTH_SECRET the same across upgrades. Changing it invalidates all existing sessions and authentication data.

Resource Recommendations

Deployment	RAM	Disk	CPU
Standalone (embedded MongoDB + Redis)	1 GB	3 GB	1 vCPU
Standalone (external MongoDB)	512 MB	2 GB	1 vCPU
Docker Compose (small)	2 GB total	5 GB	1 vCPU
Docker Compose (production)	4 GB total	20 GB	2 vCPU

The AI agent’s resource usage depends on your configured model provider (OpenRouter, OpenAI, etc.) and runs as API calls, not locally.

Security Considerations

• The embedded MongoDB and Redis bind to 127.0.0.1 only (container-internal) and are not exposed outside the container.
• Always set a strong BETTER_AUTH_SECRET (at least 32 characters) and save it for reuse across restarts and upgrades.
• Change UI_PASSWORD from the default changeme before exposing to users.
• Place a reverse proxy (nginx, Caddy, Traefik) with TLS in front of port 8080 for HTTPS.

Rotating the Admin Password

UI_PASSWORD is the source of truth for the admin password. On every container start the value is verified against the stored credential and, if it differs, the credential is replaced with the current UI_PASSWORD.

To rotate the admin password:

1. Update UI_PASSWORD in your environment (.env, compose file, or docker run -e) to the new value.
2. Restart the container (docker compose restart archmax or docker restart archmax).
3. Log in with the new password — the previous one no longer works.

Caution

Any password change made through the admin UI is overwritten on the next container restart unless UI_PASSWORD is updated to match. Treat UI_PASSWORD as authoritative.

Credential Encryption

By default, database connection passwords and test agent API keys are stored in plaintext in MongoDB. To encrypt them at rest, set the ENCRYPTION_KEY environment variable:

# Generate a key
openssl rand -base64 32

# Add to your environment
ENCRYPTION_KEY=your-generated-key

When set, all stored credentials are encrypted with AES-256-GCM before being written to MongoDB. Existing plaintext credentials continue to work and will be encrypted the next time they are updated.

Caution

Save your ENCRYPTION_KEY and keep it consistent across restarts and upgrades. If you change or lose it, stored credentials become unreadable and you will need to re-enter them.