Installation

This page covers the full install. If you just want to get running, the Quickstart is shorter.

Prerequisites

• Node.js 22 LTS — verify with ~~~node -v~~~
• pnpm 9+ — ~~~corepack enable && corepack prepare pnpm@latest --activate~~~
• Docker and Docker Compose
• Git

Clone and install dependencies

git clone git@github.com:cyb3rwize/soc-solo-os.git
cd soc-solo-os
pnpm install

Environment files

Three files carry configuration. Each has an example you copy and fill in.

Root .env

Used by scripts and Drizzle Kit.

cp .env.example .env

Required values:

• DATABASE_URL — Postgres connection string
• REDIS_URL — Redis connection string
• MEILI_HOST — Meilisearch HTTP endpoint
• MEILI_MASTER_KEY — Meilisearch admin key
• AUTH_SECRET — Session signing secret

apps/web/.env.local

Used by the web application at runtime.

cp apps/web/.env.local.example apps/web/.env.local

This file holds every runtime variable: database, Redis, MinIO, Meilisearch, Ollama, WebAuthn, and the TOTP encryption key. Every value marked CHANGE_ME must be replaced.

docker/.env

Used by Docker Compose to set service passwords.

cp docker/.env.example docker/.env

Generate strong passwords:

openssl rand -base64 32

Use one output for POSTGRES_PASSWORD, another for REDIS_PASSWORD, another for MINIO_ROOT_PASSWORD, another for MEILI_MASTER_KEY. The same values must appear in apps/web/.env.local — the app needs them to connect.

Start the data services

cd docker
docker compose up -d

This starts:

• Postgres 16 with pgvector — port 5433
• Redis 7 — port 6379
• MinIO — ports 9000 and 9001
• Meilisearch — port 7700

Verify all are healthy:

docker compose ps

Apply database migrations

cd ../packages/db
pnpm drizzle-kit migrate

To inspect the created tables:

docker exec -it soc_postgres psql -U soc -d soc_solo -c "\\dt"

Create your owner account

ATHELOS is single-user by design. Seed one owner:

cd ../..
SEED_EMAIL=you@example.com SEED_PASSWORD='your-strong-password' pnpm seed:user

Start the application

pnpm dev

Open http://localhost:3000 and sign in.

The web app runs on port 3000. The background worker runs as a separate process — start it with ~~~pnpm dev:worker~~~ in another terminal if you need report PDF generation or notification jobs.

Production deployment

For a production install:

1. Provision a server — Ubuntu 24.04, 4 GB RAM minimum
2. Install Docker, Docker Compose, UFW, and Tailscale
3. Copy the repo to the server
4. Configure the same three env files
5. Build and run the production Compose stack
6. Put a reverse proxy in front of the web app
7. Restrict access via Tailscale — do not expose ATHELOS publicly

Troubleshooting

Postgres container is unhealthy

Check port 5433 is free: ~~~ss -lntp | grep 5433~~~. If occupied, change the port in docker-compose.yml and update DATABASE_URL.

pnpm install fails with network errors

Retry. Check DNS with ~~~ping registry.npmjs.org~~~.

Login fails with valid credentials

Check AUTH_SECRET in apps/web/.env.local matches what was used when the user was seeded. If you changed it after seeding, re-seed the account.