# Runbook: Homepage dashboard

## Purpose

Operate the file-configured homelab service dashboard that Nimrod can administer without relying on web UI configuration.

## Current Service

- Product: Homepage
- Host: CTID 107 `homepage`
- IP: `192.168.0.241` via DHCP
- URL via proxy: `https://dashboard.dropcutstud.io/`
- Direct fallback: `http://192.168.0.241:3000/`
- Runtime: Docker Compose
- Compose path: `/opt/homepage/docker-compose.yml`
- Config path: `/opt/homepage/config/`
- Snapshot: `post-homepage-dashboard-mvp`

## Safety Notes

- Dashboard is a navigation/service directory, not a secrets store.
- Do not put passwords, API tokens, private URLs with embedded credentials, or recovery material in dashboard config.
- Keep config file-driven so Nimrod can administer it from SSH/config management.
- Docker socket is not mounted for MVP to avoid unnecessary privilege.

## Configuration Files

```text
/opt/homepage/docker-compose.yml
/opt/homepage/config/settings.yaml
/opt/homepage/config/services.yaml
/opt/homepage/config/bookmarks.yaml
/opt/homepage/config/widgets.yaml
```

## Add or Update a Service

1. SSH to `homepage-dashboard`.
2. Edit `/opt/homepage/config/services.yaml`.
3. Add service metadata: name, URL, description, optional monitor URL.
4. Restart or allow Homepage to reload:

   ```sh
   cd /opt/homepage
   sudo docker compose restart homepage
   ```

5. Verify:

   ```sh
   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/
   ```

6. If the service is proxied, update Unbound and Nginx as needed.
7. Update `infra/proxmox-registry.yaml` service allocation when relevant.

## Verification

```sh
systemctl is-active docker
docker ps --format '{{.Names}} {{.Status}}'
curl -sS -o /dev/null -w 'direct=%{http_code}\n' http://127.0.0.1:3000/
```

From Nimrod/LAN:

```sh
dig @192.168.0.124 dashboard.dropcutstud.io +short
curl -k --resolve dashboard.dropcutstud.io:443:192.168.0.137 https://dashboard.dropcutstud.io/ -I
```

## Backups / Restore

- Backup class: `standard`
- Backup status: configured, verified, and restore-tested on 2026-06-07
- Backup scope: `/opt/homepage/config/`, `/opt/homepage/docker-compose.yml`, and a checksum manifest
- Guest-local destination: `/var/backups/homepage/`
- Off-guest destination: `/home/piagent/backups/homepage/` on Nimrod LXC 104
- Encryption: not currently required because dashboard config must not contain secrets; if tokens or private integrations are added, switch to an approved encrypted backup path before including them.
- Schedule: manual only during bootstrap
- Retention: manual/no pruning until the broader backup destination/retention policy is selected
- Restore test required: yes for standard class; latest restore test: 2026-06-07 using an isolated temporary Homepage container bound to `127.0.0.1:13000` on CT 107

Backup script source of truth in this repo: `ansible/files/homepage-backup`.

Install/update the script with Ansible from Nimrod:

```sh
ansible homepage-dashboard -i ansible/inventories/homelab/hosts.yml \
  -m copy \
  -a 'src=ansible/files/homepage-backup dest=/usr/local/sbin/homepage-backup owner=root group=root mode=0755'
```

Manual backup command on `homepage-dashboard`:

```sh
sudo /usr/local/sbin/homepage-backup
```

Verification on `homepage-dashboard`:

```sh
cd /var/backups/homepage
sudo sha256sum -c <latest>.sha256
```

Off-guest copy from Nimrod:

```sh
mkdir -p /home/piagent/backups/homepage
scp homepage-dashboard:/var/backups/homepage/<artifact>.tar.gz /home/piagent/backups/homepage/
scp homepage-dashboard:/var/backups/homepage/<artifact>.sha256 /home/piagent/backups/homepage/
cd /home/piagent/backups/homepage && sha256sum -c <artifact>.sha256
```

Restore/rebuild outline:

1. Provision or choose an isolated test target.
2. Extract the backup artifact into a temporary directory.
3. Restore `docker-compose.yml` and `config/` to `/opt/homepage/` on the target.
4. Start Homepage with `sudo docker compose up -d` from `/opt/homepage`.
5. Verify `http://127.0.0.1:3000/` returns HTTP 200 and dashboard entries render as expected.
6. Do not overwrite production config during restore testing.

## Rollback / Recovery

For bad config:

1. Restore previous config file from git/backup/manual copy.
2. Restart Homepage container.
3. Check logs:

   ```sh
   cd /opt/homepage
   sudo docker compose logs --tail=100 homepage
   ```

For service failure:

1. Use direct service URLs from `infra/proxmox-registry.yaml` / `systems/inventory.md`.
2. Restart container:

   ```sh
   cd /opt/homepage
   sudo docker compose up -d
   ```

3. Revert CT 107 to snapshot `post-homepage-dashboard-mvp` if needed.

## Related Files / Systems

- Ticket: `tickets/active/2026-06-06-service-dashboard-registration.md`
- Registry: `infra/proxmox-registry.yaml`
- Reverse proxy runbook: `runbooks/nginx-reverse-proxy.md`
- DNS runbook: `runbooks/unbound-internal-dns.md`
- Change log: `docs/server-change-log.md`