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:

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:

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

# 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

docker build -t socktop-webterm:latest .

Run the Container

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

# 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

docker stop socktop-webterm
docker rm socktop-webterm

Configuration

Environment Variables

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

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):

ports:
  - "8082:8082"
  - "3001:3001"  # Uncomment to expose agent (container uses port 3001)

Volume Mounts

Configuration Files (Required)

volumes:
  - ./files:/files:ro  # Mount config files read-only

Persistent Data (Optional)

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:

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!

# 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:

# 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:

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:

docker exec socktop-webterm ps aux | grep socktop-agent

2. Check agent logs:

docker exec socktop-webterm cat /var/log/supervisor/socktop-agent.out.log

3. Test agent connectivity:

docker exec socktop-webterm curl http://localhost:3001/health

Configuration Not Loading

1. Verify files are mounted:

docker exec socktop-webterm ls -la /files

2. Check if files were copied:

docker exec socktop-webterm ls -la /home/socktop/.config/alacritty
docker exec socktop-webterm ls -la /home/socktop/.config/socktop

3. View entrypoint logs:

docker logs socktop-webterm 2>&1 | head -50

Font Not Loading

1. Verify font installation:

docker exec socktop-webterm fc-list | grep -i firacode

2. Rebuild image if font is missing:

docker-compose build --no-cache

Performance Issues

1. Increase resource limits in docker-compose.yml
2. Check CPU/Memory usage:

docker stats socktop-webterm

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

Maintenance

Updating the Container

# Pull latest code
git pull

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

# Restart container
docker-compose up -d

Viewing Logs

# 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

# 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:

# 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:

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:

# 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:

# 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

# 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

# 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

# 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! 🚀📊