Docker Compose Guide for AI-OS-Hub
Docker Compose Guide
This guide covers building and running the AI OS Hub full stack using Docker Compose.
Architecture
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ai-os-network ā
ā ā
ā āāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā omniroute- ā ā omniroute ā ā
ā ā redis āāāāāā (AI model routing & ā ā
ā ā (Redis 7) ā ā proxy) ā ā
ā āāāāāāāāāāāāāāāā ā :20128 (dashboard) ā ā
ā ā :20129 (API) ā ā
ā āāāāāāāāāāāā¬āāāāāāāāāāāāāāāā ā
ā ā ā
ā āāāāāāāāāāāāāāāāāāāā ā ā
ā ā freellmapi ā ā ā
ā ā (Free AI model ā ā ā
ā ā endpoints) ā ā ā
ā ā :3001 ā ā ā
ā āāāāāāāāāā¬āāāāāāāāāā ā ā
ā ā ā ā
ā āāāāāāāā¬āāāāāāāāāāāāāā ā
ā ā ā
ā āāāāāāāāāāāā¼āāāāāāāāāāā ā
ā ā ai-os-hub ā ā
ā ā (Next.js app) ā ā
ā ā :3004 ā ā
ā āāāāāāāāāāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Prerequisites
- Docker Desktop for Windows
- Git (to clone the service repos)
Required Repositories
The compose file expects these directories next to ai-os-hub/:
C:\Users\<you>\
āāā ai-os-hub/ ← this project
āāā freellmapi/ ← https://github.com/tashfeenahmed/freellmapi
āāā temp-omniroute/ ← OmniRoute server
Each must have a .env file and a Dockerfile at its root.
Quick Start
1. Build all images
 
cd C:\Users\<you>\ai-os-hub
 
docker compose build
 
This builds four container images: | Image | Source | Size | |-------|--------|------| | ai-os-hub-ai-os-hub | local Dockerfile | ~224 MB | | ghcr.io/tashfeenahmed/freellmapi | GitHub Container Registry | ~799 MB | | ai-os-hub-omniroute | local Dockerfile | ~2.46 GB | | redis:7-alpine | Docker Hub | ~30 MB |
 
2. Start all services
docker compose up -d
 
3. Check status
docker compose ps
Expected output:
NAME STATUS PORTS
ai-os-hub-ai-os-hub-1 Up (healthy) 0.0.0.0:3004->3004/tcp
ai-os-hub-freellmapi-1 Up (healthy) 0.0.0.0:3001->3001/tcp
omniroute Up (healthy) 0.0.0.0:20128-20129->20128-20129/tcp
omniroute-redis Up (healthy) 6379/tcp
 
4. Open the dashboard
Navigate to http://localhost:3004
 
Service Endpoints
Service
URL
Purpose
AI OS Hub
http://localhost:3004
Main dashboard
FreeLLMAPI
http://localhost:3001
Free AI model endpoints
OmniRoute Dashboard
http://localhost:20128
AI model routing & proxy
OmniRoute API
http://localhost:20129
Internal API
Common Commands
View logs
# All services
docker compose logs -f
# Specific service
docker compose logs -f ai-os-hub
docker compose logs -f freellmapi
docker compose logs -f omniroute
Restart a single service
docker compose restart ai-os-hub
Rebuild a single service after code changes
docker compose build ai-os-hub
docker compose up -d ai-os-hub
Stop everything
docker compose down
Stop and remove volumes (resets data)
docker compose down -v
Environment Variables
Variable
Default
Description
FREELMAPI_URL
http://freellmapi:3001
Internal URL for FreeLLMAPI
OMNIROUTE_URL
http://omniroute:20128
Internal URL for OmniRoute
PORT
3004
AI OS Hub listen port
NODE_ENV
production
Node environment
Local overrides can be placed in .env.local inside the ai-os-hub/ directory (mounted read-only into the container).
Troubleshooting
Port already in use
# Find what's using port 3004
netstat -ano | Select-String ":3004 "
# Kill the process taskkill /F /PID <PID>
 
npx kill-port 3004
# Or use a different port by editing docker-compose.yml
Container exits immediately
Check logs:
docker compose logs ai-os-hub
Common causes:
-  
- Missing
.env / .env.local files
External service repos (freellmapi, temp-omniroute) not present
Build args FREELMAPI_URL / OMNIROUTE_URL point to wrong addresses
Health check failing
Give the services more time to start (especially on first run). Check:
docker compose ps --all
docker compose logs --tail=50 ai-os-hub
Production Deployment
For production, consider:
-  
- Using tagged images instead of local builds
- Adding a reverse proxy (nginx / Caddy / Traefik) in front
- Enabling TLS/SSL via Let's Encrypt
- Persistent volumes for database data
- Resource limits in
docker-compose.yml:
services:
ai-os-hub:
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'
 
 
 
Required Repositories
The compose file expects these directories next to ai-os-hub/:
C:\Users\<you>\
āāā ai-os-hub/ ← this project
āāā freellmapi/ ← https://github.com/tashfeenahmed/freellmapi
āāā temp-omniroute/ ← OmniRoute server
Each must have a .env file and a Dockerfile at its root.
Quick Start
1. Build all images
 
cd C:\Users\<you>\ai-os-hub
 
docker compose build
 
This builds four container images: | Image | Source | Size | |-------|--------|------| | ai-os-hub-ai-os-hub | local Dockerfile | ~224 MB | | ghcr.io/tashfeenahmed/freellmapi | GitHub Container Registry | ~799 MB | | ai-os-hub-omniroute | local Dockerfile | ~2.46 GB | | redis:7-alpine | Docker Hub | ~30 MB |
 
2. Start all services
docker compose up -d
 
3. Check status
docker compose ps
Expected output:
NAME STATUS PORTS
ai-os-hub-ai-os-hub-1 Up (healthy) 0.0.0.0:3004->3004/tcp
ai-os-hub-freellmapi-1 Up (healthy) 0.0.0.0:3001->3001/tcp
omniroute Up (healthy) 0.0.0.0:20128-20129->20128-20129/tcp
omniroute-redis Up (healthy) 6379/tcp
 
4. Open the dashboard
Navigate to http://localhost:3004
 
Service Endpoints
Service
URL
Purpose
AI OS Hub
http://localhost:3004
Main dashboard
FreeLLMAPI
http://localhost:3001
Free AI model endpoints
OmniRoute Dashboard
http://localhost:20128
AI model routing & proxy
OmniRoute API
http://localhost:20129
Internal API
Common Commands
View logs
# All services
docker compose logs -f
# Specific service
docker compose logs -f ai-os-hub
docker compose logs -f freellmapi
docker compose logs -f omniroute
Restart a single service
docker compose restart ai-os-hub
Rebuild a single service after code changes
docker compose build ai-os-hub
docker compose up -d ai-os-hub
Stop everything
docker compose down
Stop and remove volumes (resets data)
docker compose down -v
Environment Variables
Variable
Default
Description
FREELMAPI_URL
http://freellmapi:3001
Internal URL for FreeLLMAPI
OMNIROUTE_URL
http://omniroute:20128
Internal URL for OmniRoute
PORT
3004
AI OS Hub listen port
NODE_ENV
production
Node environment
Local overrides can be placed in .env.local inside the ai-os-hub/ directory (mounted read-only into the container).
Troubleshooting
Port already in use
# Find what's using port 3004
netstat -ano | Select-String ":3004 "
# Kill the process taskkill /F /PID <PID>
 
npx kill-port 3004
# Or use a different port by editing docker-compose.yml
Container exits immediately
Check logs:
docker compose logs ai-os-hub
Common causes:
-  
- Missing
.env / .env.local files
External service repos (freellmapi, temp-omniroute) not present
Build args FREELMAPI_URL / OMNIROUTE_URL point to wrong addresses
Health check failing
Give the services more time to start (especially on first run). Check:
docker compose ps --all
docker compose logs --tail=50 ai-os-hub
Production Deployment
For production, consider:
-  
- Using tagged images instead of local builds
- Adding a reverse proxy (nginx / Caddy / Traefik) in front
- Enabling TLS/SSL via Let's Encrypt
- Persistent volumes for database data
- Resource limits in
docker-compose.yml:
services:
ai-os-hub:
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'
 
 
 
ai-os-hub/:
C:\Users\<you>\
āāā ai-os-hub/ ← this project
āāā freellmapi/ ← https://github.com/tashfeenahmed/freellmapi
āāā temp-omniroute/ ← OmniRoute server
Each must have a .env file and a Dockerfile at its root.
Quick Start
1. Build all images
 
cd C:\Users\<you>\ai-os-hub
 
docker compose build
 
This builds four container images: | Image | Source | Size | |-------|--------|------| | ai-os-hub-ai-os-hub | local Dockerfile | ~224 MB | | ghcr.io/tashfeenahmed/freellmapi | GitHub Container Registry | ~799 MB | | ai-os-hub-omniroute | local Dockerfile | ~2.46 GB | | redis:7-alpine | Docker Hub | ~30 MB |
 
2. Start all services
docker compose up -d
 
3. Check status
docker compose ps
Expected output:
NAME STATUS PORTS
ai-os-hub-ai-os-hub-1 Up (healthy) 0.0.0.0:3004->3004/tcp
ai-os-hub-freellmapi-1 Up (healthy) 0.0.0.0:3001->3001/tcp
omniroute Up (healthy) 0.0.0.0:20128-20129->20128-20129/tcp
omniroute-redis Up (healthy) 6379/tcp
 
4. Open the dashboard
Navigate to http://localhost:3004
 
Service Endpoints
Service
URL
Purpose
AI OS Hub
http://localhost:3004
Main dashboard
FreeLLMAPI
http://localhost:3001
Free AI model endpoints
OmniRoute Dashboard
http://localhost:20128
AI model routing & proxy
OmniRoute API
http://localhost:20129
Internal API
Common Commands
View logs
# All services
docker compose logs -f
# Specific service
docker compose logs -f ai-os-hub
docker compose logs -f freellmapi
docker compose logs -f omniroute
Restart a single service
docker compose restart ai-os-hub
Rebuild a single service after code changes
docker compose build ai-os-hub
docker compose up -d ai-os-hub
Stop everything
docker compose down
Stop and remove volumes (resets data)
docker compose down -v
Environment Variables
Variable
Default
Description
FREELMAPI_URL
http://freellmapi:3001
Internal URL for FreeLLMAPI
OMNIROUTE_URL
http://omniroute:20128
Internal URL for OmniRoute
PORT
3004
AI OS Hub listen port
NODE_ENV
production
Node environment
Local overrides can be placed in .env.local inside the ai-os-hub/ directory (mounted read-only into the container).
Troubleshooting
Port already in use
# Find what's using port 3004
netstat -ano | Select-String ":3004 "
# Kill the process taskkill /F /PID <PID>
 
npx kill-port 3004
# Or use a different port by editing docker-compose.yml
Container exits immediately
Check logs:
docker compose logs ai-os-hub
Common causes:
-  
- Missing
.env / .env.local files
External service repos (freellmapi, temp-omniroute) not present
Build args FREELMAPI_URL / OMNIROUTE_URL point to wrong addresses
Health check failing
Give the services more time to start (especially on first run). Check:
docker compose ps --all
docker compose logs --tail=50 ai-os-hub
Production Deployment
For production, consider:
-  
- Using tagged images instead of local builds
- Adding a reverse proxy (nginx / Caddy / Traefik) in front
- Enabling TLS/SSL via Let's Encrypt
- Persistent volumes for database data
- Resource limits in
docker-compose.yml:
services:
ai-os-hub:
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'