# Homepage.Dev

## Overview

Homepage (gethomepage.dev) is the self-hosted service dashboard for Centerpoint.
It provides a single-pane-of-glass view of all running services, organised into
three tabs that reflect the different access methods available for each service.
It also displays live Docker container status by connecting directly to the Docker
socket.

## Access

| Type     | URL                              | Notes                              |
|----------|----------------------------------|------------------------------------|
| Internal | `https://centerpoint.home.local` | LAN access via Step-CA TLS         |
| Direct   | `http://192.168.1.85:3003`       | Plain HTTP fallback                |

No external (internet-facing) Traefik route.

## Configuration

**Image:** `ghcr.io/gethomepage/homepage:latest` (v1.13.2 at time of writing)
**Compose project:** `homepage` (Portainer-managed; local file at
`/home/jeeves/docker/homepage/docker-compose.yml`)

### Ports

| Port   | Protocol | Purpose                              |
|--------|----------|--------------------------------------|
| `3003` | TCP      | Web UI (mapped from internal `3000`) |

### Traefik Labels

```yaml
traefik.enable: "true"
traefik.http.routers.homepage.rule: Host(`centerpoint.home.local`)
traefik.http.routers.homepage.entrypoints: websecure
traefik.http.routers.homepage.tls.certresolver: step-ca
traefik.http.services.homepage.loadbalancer.server.port: 3000
```

Internal-only route on `centerpoint.home.local`.

### Environment Variables

| Variable                  | Value                                                      |
|---------------------------|------------------------------------------------------------|
| `PUID`                    | `1000`                                                     |
| `PGID`                    | `1000`                                                     |
| `LOG_TARGETS`             | `stdout`                                                   |
| `HOMEPAGE_ALLOWED_HOSTS`  | `gethomepage.dev,192.168.1.64:3003,localhost:3003`         |

### Dashboard Structure

Homepage is configured with three tabs:

| Tab                  | Service suffix | Description                                   |
|----------------------|----------------|-----------------------------------------------|
| **External Secure**  | (plain names)  | Services via `*.jeeves5454.ddns.net` or `*.jeevesconsults.ca` |
| **Internal Secure**  | `(LAN)`        | Services via `*.home.local` through Traefik   |
| **Internal Unsecured** | `(IP)`       | Services via direct `http://IP:port`          |

The default tab is set to **Internal Secure**.

Services can appear in multiple tabs if they have multiple access routes. Docker
container status widgets (`server: centerpoint`, `container: <name>`) are applied
to services where applicable.

### Configuration Files

All config files live under `/home/jeeves/docker/homepage/config/`:

| File             | Purpose                                       |
|------------------|-----------------------------------------------|
| `settings.yaml`  | Dashboard title, theme, background, tab layout |
| `services.yaml`  | All service entries grouped by tab and category |
| `widgets.yaml`   | Top-bar info widgets (system stats, weather, etc.) |
| `bookmarks.yaml` | Bookmark groups (if used)                     |
| `docker.yaml`    | Docker socket connection config for container status |

## Volumes / Bind Mounts

| Host Path                              | Container Path        | Purpose                    |
|----------------------------------------|-----------------------|----------------------------|
| `/home/jeeves/docker/homepage/config`  | `/app/config`         | All dashboard config files |
| `/var/run/docker.sock`                 | `/var/run/docker.sock:ro` | Read-only Docker socket for container status |

## Dependencies

- Docker socket for live container status display
- Traefik on `traefik-net` for the `centerpoint.home.local` route
- API keys for service widgets (stored in `services.yaml` — secrets should be kept
  in a `secrets.yaml` file or environment variables, not committed to version control)

## Notes / Gotchas

- Homepage requires group names to be **globally unique** across all tabs. The
  `(LAN)` and `(IP)` suffixes on group names solve this constraint for the multi-tab
  layout.
- `HOMEPAGE_ALLOWED_HOSTS` must include any hostname or IP:port used to access the
  dashboard; otherwise Homepage returns a 403.
- The Docker socket mount allows Homepage to show live container state. Homepage
  accesses it read-only and does not have the ability to start or stop containers.
- Config changes take effect immediately on file save — no container restart required.
- Quick Launch search only finds services listed in `services.yaml`. To enable
  search indexing for descriptions, set `searchDescriptions: true` in `settings.yaml`.

---
*Last Updated: 2026-06-16*