# Homepage with Tailscale Integration

![Homepage with Tailscale](https://raw.githubusercontent.com/gethomepage/homepage/main/docs/assets/logo.png "Homepage")

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