> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencompany.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker (Legacy Reference)

> Historical Docker Compose topology for MachinaOs — no longer the recommended deployment path

# Docker (Legacy Reference)

<Warning>
  **This is a legacy reference, not the recommended path.** The Docker Compose files,
  the `docker/` directory, and the `scripts/docker.js` wrapper have been removed from the
  MachinaOs repository. This page documents the historical 4-container topology for reference
  and self-hosting only.

  The current deployment path is the built-in self-deploy CLI (`machina deploy up`). See
  [Production Deployment](/deployment/production) for the supported, one-command workflow.
</Warning>

<Info>
  For local development you do not need Docker at all. Run everything with the `machina` CLI:
  `npx machina dev` (hot reload) or `npx machina start`. See [Installation](/installation) for
  the full local setup (Node.js 22+, Python 3.12+, uv).
</Info>

## Prerequisites

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

## Historical Quick Start

<Warning>
  The `npm run docker:*` scripts and the compose files below are no longer present in the repo.
  These commands are shown only to describe how the legacy stack was built and started.
</Warning>

```bash theme={null}
# Clone the repository
git clone https://github.com/trohitg/MachinaOS.git
cd MachinaOs

# Build images (legacy — scripts removed)
npm run docker:build

# Start all services (legacy — scripts removed)
npm run docker:up
```

The legacy stack ran 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)

<Info>
  This container topology does **not** include Temporal, which the current runtime supervises
  in-process (gRPC on 7233, Web UI on 8080) via the pooch-downloaded `temporal` CLI, nor the
  persistent Node.js executor sidecar (port 3020) the backend now runs alongside itself.
</Info>

## Container Overview

| Container | Image              | Port | Purpose            |
| --------- | ------------------ | ---- | ------------------ |
| frontend  | machinaos-frontend | 3000 | React UI (nginx)   |
| backend   | machinaos-backend  | 3010 | FastAPI API server |
| whatsapp  | machinaos-whatsapp | 9400 | WhatsApp bridge    |
| redis     | redis:7-alpine     | 6379 | Cache (optional)   |

## Configuration

### Environment Variables

MachinaOs bootstraps its configuration from `.env.template` (copy it to `.env` and override).
For the legacy container stack, the relevant variables were:

```bash theme={null}
# 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 are entered in the Credentials modal at runtime (encrypted at rest),
# not required as environment variables.
```

<Info>
  API keys for LLM providers are managed in the app's Credentials modal and stored encrypted
  in a separate `credentials.db`. You do not set `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` as
  environment variables.
</Info>

### Redis (Optional)

Redis is disabled by default for local development. To enable:

```bash theme={null}
# In .env
REDIS_ENABLED=true
```

Then start with Redis profile:

```bash theme={null}
docker-compose --profile redis up -d
```

## Common Commands

```bash theme={null}
# 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:

| Service      | URL                                                          |
| ------------ | ------------------------------------------------------------ |
| Frontend     | [http://localhost:3000](http://localhost:3000)               |
| Backend API  | [http://localhost:3010](http://localhost:3010)               |
| Health Check | [http://localhost:3010/health](http://localhost:3010/health) |
| WebSocket    | ws\://localhost:3010/ws/status                               |

## Health Checks

All containers include health checks:

```bash theme={null}
# Check container health
docker-compose ps

# Check backend health
curl http://localhost:3010/health
```

Expected health response (the `version` field reflects the installed package version):

```json theme={null}
{
  "status": "healthy",
  "redis_enabled": false,
  "version": "0.0.92"
}
```

## Troubleshooting

<Accordion title="Container won't start">
  Check logs for errors:

  ```bash theme={null}
  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
</Accordion>

<Accordion title="Frontend can't connect to backend">
  * Verify both containers are running: `docker-compose ps`
  * Check network: containers should be on same network
  * Check CORS settings in backend `.env`
</Accordion>

<Accordion title="WhatsApp service issues">
  ```bash theme={null}
  # Check WhatsApp logs
  docker-compose logs whatsapp

  # Restart WhatsApp service
  docker-compose restart whatsapp
  ```
</Accordion>

<Accordion title="Out of disk space">
  Clean up Docker resources:

  ```bash theme={null}
  docker system prune -af
  docker builder prune -af
  ```
</Accordion>

## Resource Usage

Typical resource consumption:

| Container | Memory   | CPU    |
| --------- | -------- | ------ |
| frontend  | \~50 MB  | Low    |
| backend   | \~150 MB | Medium |
| whatsapp  | \~30 MB  | Low    |
| redis     | \~10 MB  | Low    |

## Data Persistence

Data is stored in Docker volumes:

| Volume        | Purpose                  |
| ------------- | ------------------------ |
| backend-data  | SQLite database, uploads |
| whatsapp-data | WhatsApp session         |
| redis-data    | Cache data               |

To backup data:

```bash theme={null}
docker cp machinaos-backend-1:/app/data ./backup
```

## Development Mode

For local development you do not use Docker. Run everything with the `machina` CLI:

```bash theme={null}
npx machina dev    # Frontend + backend with hot reload
# or
npx machina start  # Start all services
```

This starts the client (3000), backend (3010), the Node.js executor sidecar (3020), the
WhatsApp bridge (9400), and the supervised Temporal dev server (gRPC 7233, Web UI 8080).

## Next Steps

<CardGroup cols={2}>
  <Card title="Production Deployment" icon="server" href="/deployment/production">
    The recommended path: one-command `machina deploy up` to a cloud VM
  </Card>

  <Card title="Installation" icon="gear" href="/installation">
    Local setup and full configuration reference
  </Card>
</CardGroup>