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:**
```json
{
  "tls_ca": "/home/socktop/.config/socktop/rpi-master.pem"
}
```

**After:**
```json
{
  "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

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

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

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