Skip to main content

​
Docker Setup

The easiest way to run MachinaOs is with Docker Compose.

​
Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+
  • 2GB RAM minimum

​
Quick Start

# Clone the repository
git clone https://github.com/trohitg/MachinaOS.git
cd MachinaOs

# Build images
npm run docker:build

# Start all services
npm run docker:up
This starts 4 containers:
  • frontend - React app on port 3000
  • backend - FastAPI server on port 3010
  • whatsapp - Go WhatsApp service on port 9400
  • redis - Cache on port 6379 (optional)

​
Container Overview

ContainerImagePortPurpose
frontendmachinaos-frontend3000React UI
backendmachinaos-backend3010API server
whatsappmachinaos-whatsapp9400WhatsApp bridge
redisredis:7-alpine6379Cache (optional)

​
Configuration

​
Environment Variables

Create a .env file in the project root: 
# Ports
VITE_CLIENT_PORT=3000
PYTHON_BACKEND_PORT=3010
WHATSAPP_RPC_PORT=9400

# Authentication
AUTH_MODE=single
JWT_SECRET_KEY=your-secret-key-min-32-chars

# Cache (optional)
REDIS_ENABLED=false

# AI API Keys (optional)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

​
Redis (Optional)

Redis is disabled by default for local development. To enable: 
# In .env
REDIS_ENABLED=true
Then start with Redis profile: 
docker-compose --profile redis up -d

​
Common Commands

# Start services
npm run docker:up

# View logs
npm run docker:logs

# Stop all services
npm run docker:down

# Rebuild after code changes
npm run docker:build && npm run docker:up

# Stop and remove volumes (clean slate)
docker-compose down -v

# View specific service logs
docker-compose logs -f backend

# Restart specific service
docker-compose restart backend

​
Accessing Services

After starting, access:
ServiceURL
Frontendhttp://localhost:3000
Backend APIhttp://localhost:3010
Health Checkhttp://localhost:3010/health
WebSocketws://localhost:3010/ws/status

​
Health Checks

All containers include health checks: 
# Check container health
docker-compose ps

# Check backend health
curl http://localhost:3010/health
Expected health response: 
{
  "status": "healthy",
  "redis_enabled": false,
  "version": "1.0.0"
}

​
Troubleshooting

Check logs for errors:
docker-compose logs backend
docker-compose logs frontend
Common issues:
  • Port already in use: Change port in .env
  • Missing environment variables: Check .env file exists
  • Verify both containers are running: docker-compose ps
  • Check network: containers should be on same network
  • Check CORS settings in backend .env
# Check WhatsApp logs
docker-compose logs whatsapp

# Restart WhatsApp service
docker-compose restart whatsapp
Clean up Docker resources:
docker system prune -af
docker builder prune -af

​
Resource Usage

Typical resource consumption:
ContainerMemoryCPU
frontend~50 MBLow
backend~150 MBMedium
whatsapp~30 MBLow
redis~10 MBLow

​
Data Persistence

Data is stored in Docker volumes:
VolumePurpose
backend-dataSQLite database, uploads
whatsapp-dataWhatsApp session
redis-dataCache data
To backup data: 
docker cp machinaos-backend-1:/app/data ./backup

​
Development Mode

For development with hot reload: 
# Use development compose file
docker-compose -f docker-compose.dev.yml up
Or run services separately: 
npm run dev  # Starts frontend + backend with hot reload

​
Next Steps

Production Deployment

Deploy to a server with nginx and SSL

Configuration

Full environment variable reference