Files

DAM Updater 6800bd71d6 chore: replace stale draft with canonical ts-TEMPLATE form for ts-homepage

- Replace alternate template form (with {{YOUR_TAILSCALE_AUTHKEY}}, sys_module
  cap, hardcoded homepage.damconsulting.net serve.json) with the canonical
  ts-TEMPLATE pattern: Tailscale sidecar + Homepage, both via network_mode
- Use named volume for config dir; default settings/services/bookmarks/widgets
  files included as starting points for the user to customize
- Add SECURITY.md and proper .gitignore (incl. Homepage's auto-generated
  custom.css/custom.js/docker.yaml/kubernetes.yaml/proxmox.yaml stubs +
  logs/)
- serve.headscale.json now uses the actual MagicDNS base domain
  (homepage.damconsulting.net) so the user has a working starting point
  to edit, not a {{service}} placeholder that doesn't resolve
- Verified: dashboard renders at homepage.damconsulting.net

2026-08-03 15:48:56 -04:00

4.0 KiB

Raw Blame History

Homepage with Tailscale Integration

This project sets up a Homepage dashboard instance with Tailscale VPN integration using Docker Compose.

Homepage is a self-hosted dashboard that links to all your self-hosted services — perfect for giving you a single URL that shows the state of your homelab.

Quick Start (Tailscale)

Copy the example environment file and fill in your values:
```
cp .env.example .env
```
Edit .env and set:
- TS_AUTHKEY — your Tailscale auth key
- TZ — your local timezone (e.g., America/New_York)
Start the stack:
```
docker compose up -d
```
Customize the dashboard by editing homepage/config/ files (see Configuration below)
Access Homepage at http://homepage.<your-tailnet>.ts.net

Headscale

If you're using Headscale instead of Tailscale:

Copy the example environment file:
```
cp .env.example .env
```
Edit .env and set:
- TS_AUTHKEY — your Headscale auth key
- TS_LOGIN_SERVER — your Headscale server URL

Switch to the Headscale serve config:

cp tailscale/config/serve.headscale.json tailscale/config/serve.json

Edit serve.json to use your actual domain. The default in this file uses homepage.damconsulting.net (Kevin's Headscale base domain) — replace it with your own if your setup differs.
Start the stack:
```
docker compose up -d
```
Access Homepage at http://homepage.yourdomain.com

Configuration

Switching Serve Configs

Environment	File to use	Notes
Tailscale (default)	`tailscale/config/serve.json`	Supports HTTP + HTTPS with certs
Headscale	`tailscale/config/serve.headscale.json`	HTTP only

After changing the serve config, restart the sidecar:

docker compose restart homepage-ts

When the sidecar restarts, restart the homepage container too so it re-joins the new network namespace:

docker compose restart homepage

Dashboard Configuration

Homepage reads its dashboard layout from YAML files in ./homepage/config/:

settings.yaml — global theme, layout, colors
services.yaml — the services shown on the dashboard
bookmarks.yaml — link groups
widgets.yaml — info widgets (search bar, weather, time, etc.)
docker.yaml — Docker container monitoring (if you mount the docker socket)

The repo includes a starter services.yaml with placeholder entries. Edit the files to match the services you actually run on your tailnet (e.g., point entries to your other ts-* services at http://<service>.<your-tailnet>, etc.).

See https://gethomepage.dev/configs/ for the full reference.

After editing config files, no restart is needed — Homepage hot-reloads.

Optional: Direct Host Access

Uncomment the ports section in docker-compose.yml if you need direct access without Tailscale:

ports:
  - 3000:3000

Optional: Docker Socket Mount

To let Homepage show running containers as widgets, uncomment this volume mount in docker-compose.yml:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Security note: This gives the container read access to your Docker daemon. Only enable this on a trusted tailnet.

Notes

HOMEPAGE_ALLOWED_HOSTS: "*" is set in the compose file because the Tailscale sidecar handles auth. If you expose Homepage outside the tailnet, restrict this to your actual hostnames.
First-run shows the default "Welcome to Homepage" layout. Edit services.yaml to replace placeholders with your real services.

4.0 KiB Raw Blame History