OtterWiki¶

Wiki application for homelab documentation, automatically synced from tower-fleet repository.

Overview¶

URL: https://otterwiki.bogocat.com
Namespace: otterwiki
Image: redimp/otterwiki:2
Authentication: Authentik forward auth with custom headers

Architecture¶

                                    ┌─────────────────────────────┐
                                    │         OtterWiki Pod       │
┌─────────────┐    ┌─────────────┐  │  ┌───────────┐ ┌──────────┐ │
│   GitHub    │───▶│  git-sync   │──┼─▶│ sync.sh   │─│otterwiki │ │
│ tower-fleet │    │  sidecar    │  │  │ exechook  │ │   :80    │ │
└─────────────┘    └─────────────┘  │  └───────────┘ └──────────┘ │
      ▲                             │        │             │       │
      │                             │        ▼             ▼       │
      │                             │  ┌─────────────────────┐     │
   60s poll                         │  │   /app-data PVC     │     │
   (SSH auth)                       │  │   (wiki git repo)   │     │
                                    │  └─────────────────────┘     │
                                    └─────────────────────────────┘

Git-Sync Sidecar¶

Automatically syncs /docs from tower-fleet to OtterWiki every 60 seconds.

How It Works¶

git-sync polls the private GitHub repo via SSH
On new commits, triggers the sync script via GITSYNC_EXECHOOK_COMMAND
Sync script copies docs to wiki's internal git repository
OtterWiki serves the updated content immediately

Components¶

Component	Type	Purpose
`git-sync-ssh`	Secret	SSH private key for GitHub
`git-sync-known-hosts`	ConfigMap	GitHub SSH host fingerprints
`otterwiki-sync-scripts`	ConfigMap	Sync script (`sync-to-wiki.sh`)
`ssh-setup`	InitContainer	Copies SSH key with correct permissions

SSH Key Permissions¶

Kubernetes secrets mount with 0440 permissions (group read), which SSH rejects. Solution: initContainer copies the key to an emptyDir with 0600 permissions.

initContainers:
- name: ssh-setup
  image: busybox:1.36
  command: ["sh", "-c", "cp /secret/ssh /ssh/id_rsa && chmod 600 /ssh/id_rsa"]
  volumeMounts:
  - name: git-ssh-secret
    mountPath: /secret
  - name: ssh-ready
    mountPath: /ssh

Authentication¶

OtterWiki uses non-standard proxy headers (x-otterwiki-*), requiring an Authentik property mapping.

Authentik Setup¶

Property Mapping (Customization > Property Mappings > Scope Mapping):

return {
    "ak_proxy": {
        "user_attributes": {
            "additionalHeaders": {
                "x-otterwiki-name": request.user.username,
                "x-otterwiki-email": request.user.email,
                "x-otterwiki-permissions": "READ,WRITE,UPLOAD,ADMIN"
            }
        }
    }
}

Proxy Provider: Forward auth mode, external host https://otterwiki.bogocat.com, add property mapping
Application: Link to provider, slug otterwiki
Outpost: Add application to embedded outpost

See /root/tower-fleet/docs/reference/authentik-forward-auth-patterns.md for the full pattern.

Deployment¶

# Deploy all manifests
kubectl apply -f /root/tower-fleet/manifests/apps/otterwiki/

# Create SSH secret (if not exists)
kubectl create secret generic git-sync-ssh -n otterwiki \
  --from-file=ssh=/root/.ssh/id_rsa

# Create known_hosts (if not exists)
kubectl create configmap git-sync-known-hosts -n otterwiki \
  --from-literal=known_hosts="github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl"

Troubleshooting¶

Check git-sync status¶

kubectl logs -n otterwiki -l app=otterwiki -c git-sync --tail=30

Verify docs synced¶

kubectl exec -n otterwiki deployment/otterwiki -c git-sync -- ls /tmp/git/current/docs/

SSH authentication errors¶

# Check SSH key permissions in container
kubectl exec -n otterwiki deployment/otterwiki -c git-sync -- ls -la /etc/git-secret/

# Test SSH from host
ssh -T git@github.com

Sync script not running¶

Check exechook output in git-sync logs. The script runs with 30s timeout after each git pull.

Files¶

Manifests: /root/tower-fleet/manifests/apps/otterwiki/
Deployment: deployment.yaml (includes sync script ConfigMap)
Ingress: ingress.yaml (forward auth + outpost)