socktop-webterm/files/README.md

# Configuration Files Directory

This directory contains configuration files that will be mounted into the Docker container at runtime.

## Docker Usage

When using Docker (via `docker-compose.yml` or `scripts/docker-quickstart.sh`):

1. **Files are mounted directly** to the proper locations in the container:
   - `alacritty.toml` → `/home/socktop/.config/alacritty/alacritty.toml`
   - `catppuccin-frappe.toml` → `/home/socktop/.config/alacritty/catppuccin-frappe.toml`
   - `profiles.json` → `/home/socktop/.config/socktop/profiles.json`
   - `*.pem` certificates → `/home/socktop/.config/socktop/certs/`

2. **Files are read-only** in the container (mounted with `:ro` flag)

3. **To update configuration**: 
   - Edit files in this directory on your host
   - Changes are immediately visible in the container (no restart needed for most configs)
   - For some changes, restart may be needed: `docker-compose restart` or `scripts/docker-quickstart.sh restart`

## Required Files

Place your actual configuration files in this directory before building/running the container:

### 1. Alacritty Configuration

**`alacritty.toml`**
- Terminal emulator configuration
- Copy from: `alacritty.toml.example`
- Customize font, opacity, colors, key bindings

**`catppuccin-frappe.toml`**
- Catppuccin Frappe color theme for Alacritty
- Copy from: `catppuccin-frappe.toml.example`
- Matches the web interface theme

### 2. socktop Configuration

**`profiles.json`**
- socktop profile definitions for your remote systems
- Copy from: `profiles.json.example`
- Update with your actual host IPs and connection details

### 3. SSH Certificates (Optional)

**`rpi-master.pem`**
- SSH private key for master node
- **Permissions**: Must be `600` (will be auto-fixed by entrypoint)
- Only needed if connecting to remote systems

**`rpi-worker-1.pem`, `rpi-worker-2.pem`, `rpi-worker-3.pem`**
- SSH private keys for worker nodes
- **Permissions**: Must be `600`
- Optional - add as needed for your systems

**Note**: If no certificates are provided, the container will still work for local monitoring.

### 4. Docker-Specific Notes

- Files are mounted directly from this directory to their final locations in the container
- Files are mounted read-only (`:ro`) for security
- Certificate permissions should be `600` on the host before mounting
- For local testing, you can comment out the certificate mounts in docker-compose.yml
- Without certificates, the container will still work for local monitoring

**`rpi-worker-1.pem`**
- SSH private key for worker node 1
- **IMPORTANT**: Set permissions to 600

**`rpi-worker-2.pem`**
- SSH private key for worker node 2
- **IMPORTANT**: Set permissions to 600

**`rpi-worker-3.pem`**
- SSH private key for worker node 3
- **IMPORTANT**: Set permissions to 600

## Quick Setup

```bash
# Copy example files
cp alacritty.toml.example alacritty.toml
cp catppuccin-frappe.toml.example catppuccin-frappe.toml
cp profiles.json.example profiles.json

# Copy your SSH keys (from wherever you have them)
cp /path/to/your/rpi-master.pem .
cp /path/to/your/rpi-worker-1.pem .
cp /path/to/your/rpi-worker-2.pem .
cp /path/to/your/rpi-worker-3.pem .

# Set correct permissions on SSH keys
chmod 600 *.pem
```

## Security Notes

### SSH Keys

**DO NOT commit private keys to version control!**

The `.gitignore` file should already exclude `*.pem` files, but verify:

```bash
# Check that keys are ignored
git status

# If keys appear, add to .gitignore
echo "files/*.pem" >> ../.gitignore
```

### File Permissions

SSH keys must have restrictive permissions:

```bash
# Set correct permissions (required)
chmod 600 *.pem

# Verify
ls -la *.pem
# Should show: -rw------- (600)
```

### Read-Only Mounting

Files are mounted read-only into the container for security:

```yaml
volumes:
  - ./files:/files:ro  # :ro = read-only
```

This prevents the container from modifying your configuration files.

## Customization

### Alacritty Configuration

Edit `alacritty.toml` to customize:

```toml
[window]
opacity = 0.95  # Transparency (0.0 - 1.0)

[font]
size = 11.0  # Font size

[colors]
# Theme is imported from catppuccin-frappe.toml
```

### socktop Profiles

Edit `profiles.json` to add/modify systems:

```json
{
  "profiles": {
    "my-server": {
      "name": "My Server",
      "host": "192.168.1.100",
      "port": 3000,
      "auth": {
        "type": "ssh_key",
        "username": "user",
        "key_path": "~/.config/socktop/my-server.pem"
      },
      "tags": ["production"],
      "color": "#a6d189"
    }
  }
}
```

## Troubleshooting

### Files Not Loading

If configuration files aren't being loaded in the container:

1. **Check files exist:**
   ```bash
   ls -la files/
   ```

2. **Check container can see them:**
   ```bash
   docker exec socktop-webterm ls -la /files
   ```

3. **Check they were 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
   ```

4. **Check entrypoint logs:**
   ```bash
   docker logs socktop-webterm 2>&1 | head -50
   ```

### SSH Key Issues

If SSH authentication fails:

1. **Verify permissions:**
   ```bash
   ls -la *.pem
   # Should show: -rw------- (600)
   ```

2. **Check key format:**
   ```bash
   head -1 rpi-master.pem
   # Should show: -----BEGIN ... PRIVATE KEY-----
   ```

3. **Test key manually:**
   ```bash
   ssh -i rpi-master.pem user@host
   ```

### Font Not Rendering

If FiraCode Nerd Font doesn't work:

1. **Verify font name in config:**
   ```toml
   [font]
   normal = { family = "FiraCode Nerd Font Mono", style = "Regular" }
   ```

2. **Check font is installed in container:**
   ```bash
   docker exec socktop-webterm fc-list | grep -i firacode
   ```

## Directory Structure

```
files/
├── README.md                          # This file
├── alacritty.toml.example            # Example Alacritty config
├── alacritty.toml                    # Your Alacritty config (create this)
├── catppuccin-frappe.toml.example   # Example theme
├── catppuccin-frappe.toml           # Your theme (create this)
├── profiles.json.example             # Example profiles
├── profiles.json                     # Your profiles (create this)
├── rpi-master.pem                    # Your SSH keys (add these)
├── rpi-worker-1.pem
├── rpi-worker-2.pem
└── rpi-worker-3.pem
```

## Validation Checklist

Before running the container, verify:

- [ ] `alacritty.toml` exists and is valid TOML
- [ ] `catppuccin-frappe.toml` exists and is valid TOML
- [ ] `profiles.json` exists and is valid JSON
- [ ] All `.pem` files exist
- [ ] All `.pem` files have 600 permissions
- [ ] No `.pem` files are committed to git
- [ ] Host IPs in `profiles.json` are correct
- [ ] SSH keys match the systems in `profiles.json`

## References

- **Alacritty Config**: https://github.com/alacritty/alacritty/blob/master/alacritty.yml
- **Catppuccin Theme**: https://github.com/catppuccin/alacritty
- **socktop Docs**: https://jasonwitty.github.io/socktop/
- **Docker Docs**: See `../DOCKER_DEPLOYMENT.md`