openboatmobile-ai/docs/DOCKER_VS_DIRECT.md

# Docker vs Direct Installation Guide

## Overview

OpenBoatmobile now supports two deployment modes for Hermes Agent:

1. **Docker Container** (default, `docker_enabled = true`)
   - Runs Hermes in a Docker container
   - Isolated environment, easier updates
   - Slightly higher resource usage

2. **Direct Installation** (`docker_enabled = false`)
   - Installs Hermes directly on the host system
   - Lower resource usage, faster startup
   - `hermes` command available in PATH
   - Better for dedicated VPS environments

## Configuration

### Enable Direct Installation

**In `.env` file:**
```bash
TF_VAR_docker_enabled=false
```

**In `terraform.tfvars`:**
```hcl
docker_enabled = false
```

### Default Behavior

- `docker_enabled = true` (Docker container) - **Default**
- `docker_enabled = false` (Direct installation)

## Deployment Differences

### Docker Mode (`docker_enabled = true`)

**Installation:**
- Installs Docker and docker-compose
- Pulls `nousresearch/hermes-agent:latest`
- Runs in container with volume mounts

**Management:**
```bash
# Check status
docker ps | grep hermes

# View logs
docker logs hermes

# Restart
docker restart hermes

# Access hermes CLI
docker exec hermes hermes --help
```

**Resource Usage:**
- ~200MB additional RAM for Docker daemon
- Container overhead (~50MB RAM)
- Isolated filesystem

### Direct Mode (`docker_enabled = false`)

**Installation:**
- Installs `uv` package manager from Astral
- Clones `github.com/NousResearch/hermes-agent` repository
- Creates Python 3.11 virtual environment
- Installs with `uv pip install -e ".[messaging]"` (Discord/Slack/Telegram support)
- Creates `/usr/local/bin/hermes` wrapper script

**Management:**
```bash
# Check status
systemctl status hermes.service

# View logs
journalctl -u hermes.service -f

# Restart
systemctl restart hermes.service

# Access hermes CLI directly
hermes --help
hermes gateway status
```

**Resource Usage:**
- Minimal overhead (~20MB RAM for venv)
- Direct process execution
- Shared filesystem with host

## File Locations

### Docker Mode
```
/home/hermes/.hermes/          # Config and data (host)
/var/lib/docker/                # Container runtime
```

### Direct Mode
```
/home/hermes/.hermes/               # Config and data
/home/hermes/hermes-agent/          # Git repository
/home/hermes/hermes-agent/venv/     # Python virtual environment
/usr/local/bin/hermes              # CLI wrapper script
/root/.local/bin/uv                # uv package manager
```

## Command Line Access

### Docker Mode
```bash
# Run hermes commands
docker exec hermes hermes --version
docker exec hermes hermes gateway status

# Or create alias for convenience
echo "alias hermes='docker exec hermes hermes'" >> ~/.bashrc
```

### Direct Mode
```bash
# hermes command is directly available
hermes --version
hermes gateway status
hermes --help
```

## Health Checks

### Docker Mode
```bash
/usr/local/bin/hermes-health-check.sh
# Checks: Docker daemon, container status, port 18789, config files
```

### Direct Mode
```bash
/usr/local/bin/hermes-health-check.sh
# Checks: hermes binary, venv, process status, port 18789, config files
```

## Troubleshooting

### Docker Mode Issues
```bash
# Docker daemon not running
sudo systemctl start docker

# Container crashed
docker logs hermes
docker restart hermes

# Permission issues
sudo usermod -aG docker $USER
newgrp docker
```

### Direct Mode Issues
```bash
# hermes command not found
which hermes
ls -la /usr/local/bin/hermes
cat /usr/local/bin/hermes  # Check wrapper script content

# Virtual environment issues
ls -la ~/hermes-agent/venv/
ls -la ~/hermes-agent/venv/bin/hermes

# Check if repo was cloned
ls -la ~/hermes-agent/

# Check if uv is installed
ls -la /root/.local/bin/uv

# Service not starting
journalctl -u hermes.service -n 20
systemctl status hermes.service

# Reinstall manually
cd ~
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
/root/.local/bin/uv venv venv --python 3.11
/root/.local/bin/uv pip install -e '.[messaging]'
```

## Migration Between Modes

### From Docker to Direct
1. Set `docker_enabled = false`
2. Run `terraform apply`
3. Data in `~/.hermes/` is preserved
4. `hermes` command becomes available

### From Direct to Docker
1. Set `docker_enabled = true`
2. Run `terraform apply`
3. Data in `~/.hermes/` is preserved
4. Use `docker exec hermes hermes` for CLI access

## Performance Comparison

| Metric | Docker Mode | Direct Mode | Difference |
|--------|-------------|-------------|------------|
| RAM Usage | ~400MB | ~200MB | -50% |
| Startup Time | ~15s | ~5s | -67% |
| Disk Usage | ~2GB | ~1GB | -50% |
| hermes CLI | `docker exec` | Direct | Simpler in Direct |
| Isolation | Full | None | Docker more secure |

## Recommendations

### Use Docker Mode When:
- Running multiple services on the same server
- Wanting easy rollback/updates
- Security isolation is important
- Using cloud environments with limited control

### Use Direct Mode When:
- Dedicated VPS for Hermes only
- Wanting minimal resource usage
- Needing fastest possible startup
- Wanting direct CLI access without `docker exec`

## Examples

### Minimal Direct Installation
```hcl
# terraform.tfvars
cloud_provider = "hetzner"
agent_framework = "hermes"
docker_enabled = false
venice_api_key = "your-key"
ssh_key_names = ["your-key"]
```

### Docker Installation with Custom User
```hcl
# terraform.tfvars
cloud_provider = "hetzner"
agent_framework = "hermes"
docker_enabled = true
admin_user = "ai-admin"  # Override default 'hermes'
venice_api_key = "your-key"
ssh_key_names = ["your-key"]
```

## Support

Both modes are fully supported. The direct mode is recommended for dedicated VPS deployments where you want the `hermes` command directly available in your PATH.