socktop-webterm/DOCKER_DEPLOYMENT.md

# Docker Deployment Guide for socktop webterm

## Overview

This guide explains how to build and deploy the socktop webterm application in a Docker container. The container includes:

- Debian Trixie Slim base
- Rust-based webterm server
- xterm.js 5.5.0 with Catppuccin Frappe theme
- Alacritty terminal emulator
- FiraCode Nerd Font
- socktop-agent for monitoring
- All your custom configurations

## Prerequisites

- Docker (20.10 or later)
- Docker Compose (1.29 or later)
- Configuration files in the `files/` directory

## Quick Start

### 1. Prepare Configuration Files

Copy your configuration files to the `files/` directory:

```bash
cd webterm
mkdir -p files

# Copy your Alacritty configuration
cp /path/to/your/alacritty.toml files/
cp /path/to/your/catppuccin-frappe.toml files/

# Copy socktop configuration
cp /path/to/your/profiles.json files/

# Copy SSH keys (ensure correct permissions)
cp /path/to/your/*.pem files/
chmod 600 files/*.pem
```

**Required files in `files/` directory:**
- `alacritty.toml` - Alacritty terminal configuration
- `catppuccin-frappe.toml` - Catppuccin theme for Alacritty
- `profiles.json` - socktop profiles configuration
- `rpi-master.pem` - SSH key for master node
- `rpi-worker-1.pem` - SSH key for worker 1
- `rpi-worker-2.pem` - SSH key for worker 2
- `rpi-worker-3.pem` - SSH key for worker 3

**Example files:**
If you don't have these files yet, you can use the example templates:
```bash
cp files/alacritty.toml.example files/alacritty.toml
cp files/catppuccin-frappe.toml.example files/catppuccin-frappe.toml
cp files/profiles.json.example files/profiles.json
```

### 2. Build and Run with Docker Compose

```bash
# Build the image
docker-compose build

# Start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down
```

### 3. Access the Application

Open your browser and navigate to:
```
http://localhost:8082
```

You should see the socktop webterm interface with:
- Beautiful Catppuccin Frappe theme
- Transparent terminal window
- Link buttons to GitHub, Crates.io, and APT repository
- Terminal automatically running `socktop -P local`

## Manual Docker Commands

If you prefer not to use Docker Compose:

### Build the Image

```bash
docker build -t socktop-webterm:latest .
```

### Run the Container

```bash
docker run -d \
  --name socktop-webterm \
  -p 8082:8082 \
  -v $(pwd)/files:/files:ro \
  -v socktop-data:/home/socktop/.local/share/socktop \
  --restart unless-stopped \
  socktop-webterm:latest
```

### View Logs

```bash
# All logs
docker logs -f socktop-webterm

# Webterm logs only
docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log

# Socktop agent logs only
docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log
```

### Stop and Remove

```bash
docker stop socktop-webterm
docker rm socktop-webterm
```

## Configuration

### Environment Variables

You can customize the container behavior with environment variables in `docker-compose.yml`:

```yaml
environment:
  # Terminal type
  - TERM=xterm-256color
  
  # Timezone
  - TZ=America/New_York
  
  # Logging level (error, warn, info, debug, trace)
  - RUST_LOG=info
```

### Port Mapping

The container exposes two ports:

- **8082**: Webterm HTTP server (web interface)
- **3000**: socktop-agent (internal, usually not exposed)

To expose the socktop-agent externally (not recommended for security):
```yaml
ports:
  - "8082:8082"
  - "3001:3001"  # Uncomment to expose agent (container uses port 3001)
```

### Volume Mounts

#### Configuration Files (Required)
```yaml
volumes:
  - ./files:/files:ro  # Mount config files read-only
```

#### Persistent Data (Optional)
```yaml
volumes:
  - socktop-data:/home/socktop/.local/share/socktop  # Persist socktop data
  - ./logs:/var/log/supervisor  # Access logs on host
```

### Resource Limits

Adjust resource limits in `docker-compose.yml`:

```yaml
deploy:
  resources:
    limits:
      cpus: '2.0'      # Maximum CPU cores
      memory: 1G       # Maximum memory
    reservations:
      cpus: '0.5'      # Minimum CPU cores
      memory: 256M     # Minimum memory
```

## Security Considerations

### Container Security

The container implements several security best practices:

1. **Non-root user**: Application runs as `socktop` user (not root)
2. **No new privileges**: `security_opt: no-new-privileges:true`
3. **Read-only config mounts**: Configuration files mounted as read-only
4. **Minimal attack surface**: Only necessary ports exposed

### SSH Key Security

**IMPORTANT**: Your SSH private keys are sensitive!

```bash
# Ensure correct permissions
chmod 600 files/*.pem

# Never commit keys to git
echo "files/*.pem" >> .gitignore
```

### Network Security

The container runs in an isolated Docker network by default. Consider:

1. **Use a reverse proxy** (nginx, Traefik) with HTTPS for production
2. **Don't expose socktop-agent port** (3000) to the internet
3. **Use firewall rules** to restrict access to port 8082
4. **Enable authentication** if exposing publicly

### Production Recommendations

For production deployments:

```bash
# Use a reverse proxy with SSL
# Example with nginx:
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/certs:/etc/nginx/certs:ro \
  -v /var/run/docker.sock:/tmp/docker.sock:ro \
  jwilder/nginx-proxy

# Then expose webterm only to nginx
docker run -d \
  --name socktop-webterm \
  -p 127.0.0.1:8082:8082 \
  -e VIRTUAL_HOST=socktop.yourdomain.com \
  -e LETSENCRYPT_HOST=socktop.yourdomain.com \
  socktop-webterm:latest
```

## Troubleshooting

### Container Won't Start

Check logs:
```bash
docker-compose logs
```

Common issues:
- **Missing config files**: Ensure all required files are in `files/` directory
- **Port already in use**: Change port mapping in `docker-compose.yml`
- **Permission denied**: Check file permissions, especially `.pem` files

### Terminal Not Connecting

1. Check if socktop-agent is running:
```bash
docker exec socktop-webterm ps aux | grep socktop-agent
```

2. Check agent logs:
```bash
docker exec socktop-webterm cat /var/log/supervisor/socktop-agent.out.log
```

3. Test agent connectivity:
```bash
docker exec socktop-webterm curl http://localhost:3001/health
```

### Configuration Not Loading

1. Verify files are mounted:
```bash
docker exec socktop-webterm ls -la /files
```

2. Check if files were copied:
```bash
docker exec socktop-webterm ls -la /home/socktop/.config/alacritty
docker exec socktop-webterm ls -la /home/socktop/.config/socktop
```

3. View entrypoint logs:
```bash
docker logs socktop-webterm 2>&1 | head -50
```

### Font Not Loading

1. Verify font installation:
```bash
docker exec socktop-webterm fc-list | grep -i firacode
```

2. Rebuild image if font is missing:
```bash
docker-compose build --no-cache
```

### Performance Issues

1. **Increase resource limits** in `docker-compose.yml`
2. **Check CPU/Memory usage**:
```bash
docker stats socktop-webterm
```

3. **Reduce transparency** in Alacritty config (opacity: 1.0)
4. **Disable backdrop blur** in terminal CSS

## Maintenance

### Updating the Container

```bash
# Pull latest code
git pull

# Rebuild image
docker-compose build --no-cache

# Restart container
docker-compose up -d
```

### Viewing Logs

```bash
# All supervisor logs
docker exec socktop-webterm ls /var/log/supervisor/

# Tail specific log
docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log

# Export logs to host
docker cp socktop-webterm:/var/log/supervisor/ ./container-logs/
```

### Backing Up Configuration

```bash
# Backup volumes
docker run --rm \
  -v socktop-data:/data \
  -v $(pwd):/backup \
  debian:trixie-slim \
  tar czf /backup/socktop-backup-$(date +%Y%m%d).tar.gz /data

# Backup config files
tar czf socktop-config-backup-$(date +%Y%m%d).tar.gz files/
```

### Health Checks

The container includes a health check:

```bash
# Check health status
docker inspect --format='{{.State.Health.Status}}' socktop-webterm

# View health check logs
docker inspect socktop-webterm | jq '.[0].State.Health'
```

## Advanced Usage

### Running in Production

Example production `docker-compose.yml`:

```yaml
version: '3.8'

services:
  socktop-webterm:
    image: socktop-webterm:latest
    container_name: socktop-webterm
    restart: always
    
    ports:
      - "127.0.0.1:8082:8082"  # Only localhost
    
    volumes:
      - ./files:/files:ro
      - socktop-data:/home/socktop/.local/share/socktop
      - /etc/localtime:/etc/localtime:ro  # Use host timezone
    
    environment:
      - RUST_LOG=warn
      - TZ=UTC
    
    security_opt:
      - no-new-privileges:true
    
    cap_drop:
      - ALL
    
    networks:
      - web
    
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  web:
    external: true

volumes:
  socktop-data:
```

### Multi-Architecture Builds

Build for ARM (Raspberry Pi) and AMD64:

```bash
# Enable buildx
docker buildx create --use

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t socktop-webterm:latest \
  --push \
  .
```

### Kubernetes Deployment

Example Kubernetes manifests:

```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: socktop-webterm
spec:
  replicas: 1
  selector:
    matchLabels:
      app: socktop-webterm
  template:
    metadata:
      labels:
        app: socktop-webterm
    spec:
      containers:
      - name: socktop-webterm
        image: socktop-webterm:latest
        ports:
        - containerPort: 8082
        volumeMounts:
        - name: config
          mountPath: /files
          readOnly: true
        resources:
          limits:
            memory: "1Gi"
            cpu: "2"
          requests:
            memory: "256Mi"
            cpu: "500m"
      volumes:
      - name: config
        secret:
          secretName: socktop-config
```

## Development

### Building for Development

```bash
# Build without cache
docker-compose build --no-cache

# Build with verbose output
docker-compose build --progress=plain

# Build specific stage
docker build --target builder -t socktop-webterm:builder .
```

### Interactive Debugging

```bash
# Shell into running container
docker exec -it socktop-webterm bash

# Run container with shell
docker run -it --rm \
  -v $(pwd)/files:/files:ro \
  socktop-webterm:latest \
  /bin/bash

# Override entrypoint
docker run -it --rm \
  --entrypoint /bin/bash \
  socktop-webterm:latest
```

### Testing Changes

```bash
# Test with local changes
docker-compose up --build

# Watch logs
docker-compose logs -f

# Restart services
docker-compose restart
```

## Support

For issues and questions:

- **GitHub Issues**: https://github.com/jasonwitty/socktop/issues
- **Documentation**: https://jasonwitty.github.io/socktop/
- **Docker Hub**: (if you publish the image)

## License

Same as socktop project.

---

**Happy monitoring!** 🚀📊