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

```bash
cd webterm
```

### 2. Set Up Configuration

```bash
# 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

```bash
# 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)**

```bash
./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**

```bash
# 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:
```bash
chmod 600 files/*.pem
```

## 🛠️ Management Commands

### Using the Quick Start Script

```bash
./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

```bash
# 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:**
```bash
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:**
```bash
docker exec socktop-webterm ps aux | grep socktop-agent
```

**View agent logs:**
```bash
docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log
```

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

### Configuration Not Loading

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

**Check if copied to config directories:**
```bash
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:**
```bash
docker exec socktop-webterm fc-list | grep -i firacode
```

If missing, rebuild:
```bash
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**
   ```bash
   # Already in .gitignore, but verify:
   git status files/
   ```

2. **Use correct permissions**
   ```bash
   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:

```bash
# 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

```bash
# Monitor CPU/Memory
docker stats socktop-webterm

# View detailed stats
docker-compose stats
```

### Logs

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

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

### Environment Variables

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

### Resource Limits

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

### Volume Persistence

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

## 📦 Building for Production

### Multi-Architecture

Build for multiple platforms (AMD64, ARM64):

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

### Optimized Build

```bash
# 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

```bash
docker stack deploy -c docker-compose.yml socktop
```

### Kubernetes

Example deployment in `DOCKER_DEPLOYMENT.md`

### Standalone Docker

```bash
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

```bash
# 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`