ARKEN AI — Docker Infrastructure

Unified Docker setup for the full ARKEN AI stack. Runs all services behind an nginx reverse proxy with a single docker compose up -d.

---

Services

Service	Port	Description	Environment
nginx	80	Reverse proxy — routes all traffic	Both
Backend	8001	FastAPI orchestration (Claude Loop 1)	Both
HX Engine	8100	16-step design pipeline	Both
Frontend	—	React/Vite app (served via nginx)	Both
MongoDB	27017	Conversations, visitors, fouling cache	Both
Redis	6379	Sessions, heartbeats, SSE event streams	Both
Mongo Express	8081	MongoDB web UI	Dev only
Redis Insight	5540	Redis web UI	Dev only

nginx Routing

/api/v1/hx/*   →  hx-engine:8100   (SSE: proxy_buffering off, 300s timeout)
/api/*         →  backend:8001
/              →  frontend (Vite build / dev server)
/health        →  nginx 200 OK

The /api/v1/hx/ rule must come before /api/ to prevent misrouting.

---

File Structure

File	Purpose
docker-compose.yml	Production — hardened, no admin UIs, localhost-only ports
docker-compose.dev.yml	Development override — adds Mongo Express, Redis Insight, open ports
nginx.conf	nginx reverse proxy config with SSE support
mongo-init.js	MongoDB initialization (collections, indexes, app user)
.env.example	Credentials template

---

Quick Start

Development (local)

cd docker
cp .env.example .env
# Edit .env with your passwords and API keys
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Production (AWS)

cd docker
cp .env.example .env
# Edit .env with strong passwords (see AWS_INSTALLATION.md)
docker compose up -d

---

Environment Variables

Copy .env.example to .env and fill in all values before starting.

Key variables:

Variable	Description
ANTHROPIC_API_KEY	Claude Sonnet 4.6 API key (used by both Backend and HX Engine)
MONGODB_ROOT_PASSWORD	MongoDB root password
MONGODB_APP_PASSWORD	MongoDB app user password
HX_ENGINE_INTERNAL_SECRET	Shared secret for Backend → HX Engine service auth
APP_SHARED_PASSWORD	Shared login password for the frontend (pre-JWT)

---

Verify Services

# Check all containers
docker compose ps

# Health check
curl http://localhost/health

# MongoDB shell
docker exec -it arken-mongodb mongosh \
  -u arken_app -p $MONGODB_APP_PASSWORD \
  --authenticationDatabase admin arken_process_db

# Redis CLI
docker exec -it arken-redis redis-cli ping

---

Admin UIs (Dev only)

Available when using docker-compose.dev.yml:

UI	URL	Credentials
Mongo Express	http://localhost:8081	MONGO_EXPRESS_USERNAME / MONGO_EXPRESS_PASSWORD from .env
Redis Insight	http://localhost:5540	No auth; add host redis, port 6379

---

Common Commands

# Production
docker compose up -d
docker compose down
docker compose logs -f
docker compose logs -f hx-engine
docker compose restart

# Development
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
docker compose -f docker-compose.yml -f docker-compose.dev.yml down

# ⚠ Destructive — removes all data volumes
docker compose down -v

---

Architecture

Browser
   │
   ▼
nginx :80
   ├── /api/v1/hx/*  ──► hx-engine:8100  (SSE: proxy_buffering off)
   ├── /api/*         ──► backend:8001
   └── /              ──► frontend
           │
           ├── backend:8001  ──► MongoDB, Redis, Anthropic API
           └── hx-engine:8100 ──► Redis, MongoDB, Anthropic API

---

Volumes

Volume	Purpose
arken_mongo_data	MongoDB data files
arken_redis_data	Redis persistence
arken_redisinsight_data	Redis Insight config

docker volume ls | grep arken

---

Troubleshooting

Container won't start:

docker compose logs <service-name>

MongoDB auth failed:
Ensure mongo-init.js ran successfully:

docker compose logs mongodb | grep "arken_app"

If missing, reset and reinitialize:

docker compose down -v && docker compose up -d

Port already in use:

lsof -i :80     # nginx
lsof -i :27017  # MongoDB
lsof -i :6379   # Redis

SSE stream disconnecting:
Check nginx config has proxy_buffering off and timeout ≥ 300s for /api/v1/hx/ routes.

---

For production AWS deployment, see AWS_INSTALLATION.md.