generated from DAM/ts-TEMPLATE
DAM Updater
6800bd71d6
- 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
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# Homepage with Tailscale Integration
|
|
|
|
|
|
|
|
This project sets up a [Homepage](https://gethomepage.dev/) 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)
|
|
|
|
1. Copy the example environment file and fill in your values:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
2. Edit `.env` and set:
|
|
- `TS_AUTHKEY` — your Tailscale auth key
|
|
- `TZ` — your local timezone (e.g., `America/New_York`)
|
|
3. Start the stack:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
4. Customize the dashboard by editing `homepage/config/` files (see [Configuration](#configuration) below)
|
|
5. Access Homepage at `http://homepage.<your-tailnet>.ts.net`
|
|
|
|
## Headscale
|
|
|
|
If you're using Headscale instead of Tailscale:
|
|
|
|
1. Copy the example environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
2. Edit `.env` and set:
|
|
- `TS_AUTHKEY` — your Headscale auth key
|
|
- `TS_LOGIN_SERVER` — your Headscale server URL
|
|
3. Switch to the Headscale serve config:
|
|
```bash
|
|
cp tailscale/config/serve.headscale.json tailscale/config/serve.json
|
|
```
|
|
4. 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.
|
|
5. Start the stack:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
6. 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:
|
|
```bash
|
|
docker compose restart homepage-ts
|
|
```
|
|
|
|
When the sidecar restarts, restart the homepage container too so it re-joins the new network namespace:
|
|
```bash
|
|
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:
|
|
```yaml
|
|
ports:
|
|
- 3000:3000
|
|
```
|
|
|
|
### Optional: Docker Socket Mount
|
|
|
|
To let Homepage show running containers as widgets, uncomment this volume mount in `docker-compose.yml`:
|
|
```yaml
|
|
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.
|
|
|
|
## Links
|
|
|
|
- Official site: https://gethomepage.dev/
|
|
- Git repository: https://github.com/gethomepage/homepage
|
|
- Docker image: https://github.com/gethomepage/homepage/pkgs/container/homepage
|