socktop-webterm/DOCKER_README.md

socktop webterm - Docker Deployment

🐳 Containerized web-based terminal for socktop system monitoring

This Docker container packages the socktop webterm application with all dependencies, providing an isolated environment for running the beautiful web-based monitoring interface.

🎯 What's Inside

• Debian Trixie Slim base image
• Rust webterm server (built from source)
• xterm.js 5.5.0 with Catppuccin Frappe theme
• Alacritty terminal emulator with transparency
• FiraCode Nerd Font for beautiful monospace rendering
• socktop-agent installed via APT (port 3001)
• Supervisor for process management
• Security hardening (non-root user, minimal attack surface)

🚀 Quick Start

Prerequisites

• Docker 20.10+
• Docker Compose 1.29+
• Your configuration files (see below)

1. Clone and Navigate

cd webterm

2. Set Up Configuration

# Create configuration files from examples
cd files
cp alacritty.toml.example alacritty.toml
cp catppuccin-frappe.toml.example catppuccin-frappe.toml
cp profiles.json.example profiles.json

3. Add Your SSH Keys

# Copy your SSH private keys
cp /path/to/your/rpi-master.pem files/
cp /path/to/your/rpi-worker-*.pem files/

# Set correct permissions (IMPORTANT!)
chmod 600 files/*.pem

4. Build and Run

Option A: Use the Quick Start Script (Recommended)

./docker-quickstart.sh start

This interactive script will:

• Check Docker installation
• Verify configuration files
• Build the image
• Start the container
• Show you the access URL

Option B: Manual Docker Compose

# Build the image
docker-compose build

# Start the container
docker-compose up -d

# View logs
docker-compose logs -f

5. Access the Application

Open your browser:

http://localhost:8082

You should see:

• ✨ Beautiful Catppuccin Frappe themed interface
• 🖼️ Terminal window with macOS-style frame
• 🔗 Links to GitHub, Crates.io, and APT repository
• 💻 Terminal automatically running socktop -P local

📋 Configuration Files

All configuration files go in the files/ directory and are mounted into the container at runtime.

Required Files

File	Description	Source
alacritty.toml	Alacritty terminal config	Copy from example
catppuccin-frappe.toml	Terminal color theme	Copy from example
profiles.json	socktop remote profiles	Copy from example
*.pem	SSH private keys	Your keys

Example Configuration

See files/README.md for detailed configuration instructions.

Important: Always set correct permissions on SSH keys:

chmod 600 files/*.pem

🛠️ Management Commands

Using the Quick Start Script

./docker-quickstart.sh [COMMAND]

Available commands:

• start - Build and start the container (default)
• stop - Stop the container
• restart - Restart the container
• rebuild - Rebuild from scratch (no cache)
• logs - Show and follow logs
• shell - Open bash shell in container
• status - Show container status
• clean - Remove container and volumes
• help - Show help message

Using Docker Compose Directly

# Start
docker-compose up -d

# Stop
docker-compose down

# Restart
docker-compose restart

# View logs
docker-compose logs -f

# Rebuild
docker-compose build --no-cache

# Shell access
docker exec -it socktop-webterm bash

🔍 Troubleshooting

Container Won't Start

Check logs:

docker-compose logs

Common issues:

• Missing configuration files in files/
• Port 8082 already in use (change in docker-compose.yml)
• Incorrect permissions on .pem files (must be 600)

Terminal Not Connecting

Check socktop-agent status:

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

View agent logs:

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

Test agent:

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

Configuration Not Loading

Verify files are mounted:

docker exec socktop-webterm ls -la /files

Check if copied to config directories:

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

Font Issues

Verify font installation:

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

If missing, rebuild:

docker-compose build --no-cache

🔒 Security

Container Security Features

• ✅ Non-root user: Application runs as socktop user
• ✅ No new privileges: security_opt: no-new-privileges:true
• ✅ Read-only config: Configuration files mounted read-only
• ✅ Minimal attack surface: Only necessary ports exposed
• ✅ Resource limits: CPU and memory limits configured
• ✅ Security updates: Applied during build

Best Practices

1. Never commit SSH keys to git

   # Already in .gitignore, but verify:
   git status files/
   

2. Use correct permissions

   chmod 600 files/*.pem  # SSH keys
   chmod 644 files/*.toml  # Config files
   chmod 644 files/*.json  # JSON files
   

3. For production

   • Use a reverse proxy (nginx/Traefik) with HTTPS
   • Don't expose port 3001 (socktop-agent) externally
   • Use firewall rules to restrict port 8082
   • Consider adding authentication

4. Network isolation

   • Container runs in isolated Docker network
   • Only exposes necessary ports
   • Internal services not exposed

📊 Monitoring

Health Checks

The container includes built-in health checks:

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

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

Resource Usage

# Monitor CPU/Memory
docker stats socktop-webterm

# View detailed stats
docker-compose stats

Logs

# All logs
docker-compose logs -f

# Specific service
docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log
docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log

# Export logs
docker cp socktop-webterm:/var/log/supervisor/ ./logs/

🔧 Advanced Configuration

Custom Ports

Edit docker-compose.yml:

ports:
  - "8080:8082"  # Host:Container

Environment Variables

environment:
  - TERM=xterm-256color
  - TZ=America/New_York
  - RUST_LOG=debug  # Logging level

Resource Limits

deploy:
  resources:
    limits:
      cpus: '4.0'
      memory: 2G

Volume Persistence

volumes:
  - socktop-data:/home/socktop/.local/share/socktop
  - ./logs:/var/log/supervisor

📦 Building for Production

Multi-Architecture

Build for multiple platforms (AMD64, ARM64):

docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t socktop-webterm:latest --push .

Optimized Build

# Build with specific target
docker build --target production -t socktop-webterm:latest .

# Build with build args
docker build --build-arg RUST_VERSION=1.70 -t socktop-webterm:latest .

Image Size

Current image size: ~1.5GB (includes Rust toolchain, Node.js, fonts)

To reduce size, consider:

• Multi-stage builds (already implemented)
• Removing build dependencies after compilation
• Using Alpine base (requires significant changes)

🚢 Deployment Options

Docker Compose (Recommended)

Already configured in docker-compose.yml

Docker Swarm

docker stack deploy -c docker-compose.yml socktop

Kubernetes

Example deployment in DOCKER_DEPLOYMENT.md

Standalone Docker

docker run -d \
  --name socktop-webterm \
  -p 8082:8082 \
  -v $(pwd)/files:/files:ro \
  --restart unless-stopped \
  socktop-webterm:latest

📚 Documentation

• Full Deployment Guide: DOCKER_DEPLOYMENT.md (543 lines of detailed instructions)
• Configuration Guide: files/README.md
• Main README: README.md
• Transparency Guide: TRANSPARENCY_GUIDE.md
• Catppuccin Styling: CATPPUCCIN_STYLING.md
• Terminal Window Styling: TERMINAL_WINDOW_STYLING.md

🆘 Getting Help

Check Documentation

1. Read DOCKER_DEPLOYMENT.md for comprehensive guide
2. Check files/README.md for configuration help
3. Review logs with docker-compose logs

Common Commands Reference

# Start everything
./docker-quickstart.sh start

# View logs
docker-compose logs -f

# Restart after config change
docker-compose restart

# Full rebuild
./docker-quickstart.sh rebuild

# Shell access for debugging
docker exec -it socktop-webterm bash

# Remove everything
./docker-quickstart.sh clean

Support

• GitHub Issues: https://github.com/jasonwitty/socktop/issues
• Documentation: https://jasonwitty.github.io/socktop/
• Source Code: https://github.com/jasonwitty/socktop

🎨 Features

Beautiful UI

• Catppuccin Frappe color scheme throughout
• Transparent terminal window with backdrop blur
• macOS-style window frame with traffic lights
• Responsive design for all screen sizes

Terminal Features

• xterm.js 5.5.0 with modern addon system
• Auto-connects to local socktop-agent
• FiraCode Nerd Font with ligature support
• Configurable transparency and blur

Monitoring

• socktop-agent runs on port 3001 (to avoid conflicts with host machine's agent on port 3000)
• Supports remote host monitoring via SSH
• Profile-based configuration
• Real-time system metrics

📝 License

Same as the socktop project.

🙏 Credits

• xterm.js: https://xtermjs.org/
• Catppuccin: https://github.com/catppuccin/catppuccin
• Alacritty: https://github.com/alacritty/alacritty
• socktop: https://github.com/jasonwitty/socktop

---

Happy monitoring! 🚀📊✨

For detailed instructions, see DOCKER_DEPLOYMENT.md