socktop-webterm/docker/CONFIG-INIT-README.md

Configuration Initialization Fix

Problem

The socktop package (installed via APT) sets the socktop user's HOME directory to /var/lib/socktop, but Kubernetes ConfigMaps and Secrets mount files to /home/socktop/. This caused profiles and certificates to not be found by socktop.

Solution

A two-stage initialization process using init-config.sh:

Stage 1: Copy and Transform (init-config.sh)

Runs as root at container startup:

1. Detects the actual HOME directory of the socktop user
2. Copies configuration files from mounted locations to actual HOME
3. Rewrites paths in profiles.json to use correct HOME directory
4. Sets proper ownership
5. Switches to socktop user and executes the main entrypoint

Stage 2: Validation (entrypoint.sh)

Runs as socktop user:

1. Validates configuration files are present
2. Starts the webterm server

File Locations

Kubernetes Mounts

/home/socktop/.config/socktop/profiles.json      (ConfigMap)
/home/socktop/.config/alacritty/alacritty.toml   (ConfigMap)
/home/socktop/.config/alacritty/catppuccin-frappe.toml (ConfigMap)
/home/socktop/.config/socktop/certs/*.pem        (Secret)

Actual Locations (after init-config.sh)

/var/lib/socktop/.config/socktop/profiles.json
/var/lib/socktop/.config/alacritty/alacritty.toml
/var/lib/socktop/.config/alacritty/catppuccin-frappe.toml
/var/lib/socktop/.config/socktop/certs/*.pem

Path Rewriting

The init-config.sh script automatically rewrites paths in profiles.json:

Before:

{
  "tls_ca": "/home/socktop/.config/socktop/rpi-master.pem"
}

After:

{
  "tls_ca": "/var/lib/socktop/.config/socktop/certs/rpi-master.pem"
}

This ensures certificate paths point to the correct location in the actual HOME directory.

Dockerfile Changes

# Copy both init and entrypoint scripts
COPY docker/entrypoint.sh /entrypoint.sh
COPY docker/init-config.sh /init-config.sh
RUN chmod +x /entrypoint.sh /init-config.sh

# init-config.sh runs as root, copies configs, then switches to socktop user
ENTRYPOINT ["/init-config.sh"]

# Pass through init-config.sh -> entrypoint.sh -> webterm-server
CMD ["/entrypoint.sh", "webterm-server", "--host", "0.0.0.0", "--port", "8082"]

Execution Flow

Container Start (as root)
    ↓
[init-config.sh]
    ├─ Detect HOME directory
    ├─ Create directories in /var/lib/socktop
    ├─ Copy files from /home/socktop to /var/lib/socktop
    ├─ Rewrite paths in profiles.json
    ├─ Set ownership to socktop:socktop
    └─ Switch to socktop user
    ↓
[entrypoint.sh] (as socktop)
    ├─ Validate configuration files
    ├─ Setup Alacritty
    └─ Start webterm-server
    ↓
[webterm-server] (as socktop)
    └─ Running on port 8082

Local Development (docker-compose)

For local development, the quickstart script (scripts/docker-quickstart.sh) manually copies files to /var/lib/socktop/ using docker cp after container startup. This is because:

1. Docker Compose uses host networking mode
2. Local testing needs to connect to host's socktop-agent on port 3000
3. The init-config.sh still works, but the quickstart provides an additional safety net

Kubernetes Deployment

In K8s:

1. ConfigMap mounts profiles.json to /home/socktop/.config/socktop/
2. Secret mounts certificates to /home/socktop/.config/socktop/certs/
3. init-config.sh runs and copies everything to /var/lib/socktop/
4. Socktop reads from /var/lib/socktop/ (its actual HOME)
5. Everything works! ✅

Benefits

1. No K8s Changes Required: Existing ConfigMaps and Secrets work as-is
2. Automatic Path Correction: Certificate paths are automatically fixed
3. Works Everywhere: Same image works in K8s, Docker Compose, and standalone Docker
4. No Race Conditions: Init happens before any services start
5. Proper Security: Runs as socktop user after initialization

Troubleshooting

Profiles Not Found

Check if init-config.sh ran successfully:

docker logs <container-id> | grep "Initializing socktop webterm config"

You should see:

===================================
Initializing socktop webterm config
===================================
Socktop HOME: /var/lib/socktop
Copying configuration files...
  ✓ Copied profiles.json
  ✓ Copied alacritty.toml
  ✓ Copied catppuccin-frappe.toml
  ✓ Copied rpi-master.pem
  ...
Rewriting paths in profiles.json...
  ✓ Updated certificate paths
===================================
Configuration initialization complete
===================================

Check Files Were Copied

# In K8s
kubectl exec -n socktop socktop-webterm-<pod> -it -- \
  ls -la /var/lib/socktop/.config/socktop/

# In Docker
docker exec socktop-webterm \
  ls -la /var/lib/socktop/.config/socktop/

Verify Path Rewriting

# Check certificate paths in profiles.json
kubectl exec -n socktop socktop-webterm-<pod> -it -- \
  cat /var/lib/socktop/.config/socktop/profiles.json | grep tls_ca

Should show:

"tls_ca": "/var/lib/socktop/.config/socktop/certs/rpi-master.pem",

NOT:

"tls_ca": "/home/socktop/.config/socktop/rpi-master.pem",

Files

• docker/init-config.sh - Configuration initialization script (runs as root)
• docker/entrypoint.sh - Service startup script (runs as socktop)
• Dockerfile - Sets up both scripts as entrypoint chain
• kubernetes/01-configmap.yaml - Mounts configs to /home/socktop
• kubernetes/02-secret.yaml - Mounts certs to /home/socktop

Related Issues

This fix resolves the issue where socktop profiles were not found after deployment to K8s, while maintaining compatibility with local Docker Compose development.

---

Created: 2024-11-29 Status: Implemented and Tested