socktop-webterm/files

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

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

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

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

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

This prevents the container from modifying your configuration files.

Customization

Alacritty Configuration

Edit alacritty.toml to customize:

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

{
  "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:

   ls -la files/
   

2. Check container can see them:

   docker exec socktop-webterm ls -la /files
   

3. Check they were copied to config directories:

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

4. Check entrypoint logs:

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

SSH Key Issues

If SSH authentication fails:

1. Verify permissions:

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

2. Check key format:

   head -1 rpi-master.pem
   # Should show: -----BEGIN ... PRIVATE KEY-----
   

3. Test key manually:

   ssh -i rpi-master.pem user@host
   

Font Not Rendering

If FiraCode Nerd Font doesn't work:

1. Verify font name in config:

   [font]
   normal = { family = "FiraCode Nerd Font Mono", style = "Regular" }
   

2. Check font is installed in container:

   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