generated from DAM/ts-TEMPLATE
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
This commit is contained in:
178
README.md
178
README.md
@@ -1,111 +1,109 @@
|
||||
# Homepage with Tailscale Integration
|
||||
|
||||
|
||||
|
||||
|
||||
This project sets up a Homepage instance with Tailscale VPN integration using Docker Compose. It creates a secure, private network connection for your homepage dashboard using Tailscale, while running the Homepage application from gethomepage.dev.
|
||||
This project sets up a [Homepage](https://gethomepage.dev/) dashboard instance with Tailscale VPN integration using Docker Compose.
|
||||
|
||||
## Prerequisites
|
||||
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.
|
||||
|
||||
- Docker and Docker Compose installed on your system
|
||||
- A Tailscale account and auth key (get one from https://login.tailscale.com/admin/authkeys)
|
||||
- Basic understanding of Docker and networking concepts
|
||||
## Quick Start (Tailscale)
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
ts-homepage/
|
||||
├── docker-compose.yml
|
||||
├── tailscale/
|
||||
│ ├── tailscale-data/ # Persistent Tailscale state
|
||||
│ └── config/ # Tailscale configuration files
|
||||
└── homepage/
|
||||
└── config/ # Homepage configuration files
|
||||
```
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
1. **Clone the Repository**
|
||||
1. Copy the example environment file and fill in your values:
|
||||
```bash
|
||||
git clone https://gitea.damconsulting.llc/DAM/ts-homepage.git
|
||||
cd ts-homepage
|
||||
cp .env.example .env
|
||||
```
|
||||
2. Create Required Directories
|
||||
```bash
|
||||
mkdir -p tailscale/tailscale-data tailscale/config homepage/config
|
||||
```
|
||||
3. Configure Tailscale
|
||||
- Make sure `TS_AUTHKEY` and `TS_LOGIN_SERVER` are set in your environment (or a local .env file) before running docker compose.
|
||||
- Optionally, update the file in `tailscale/config/serve.json` if you need specific Tailscale serve configurations
|
||||
- CAUTION: Changing `"${TS_CERT_DOMAIN}:443": false` to `true` will expose the service to the internet
|
||||
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`
|
||||
|
||||
4. Configure Homepage
|
||||
- Add your Homepage configuration files to homepage/config/
|
||||
- See https://gethomepage.dev/configs/ for configuration options
|
||||
- The default setup allows all hosts (HOMEPAGE_ALLOWED_HOSTS: "*")
|
||||
## Headscale
|
||||
|
||||
5. Start the Services
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
If you're using Headscale instead of Tailscale:
|
||||
|
||||
## Services
|
||||
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`
|
||||
|
||||
### homepage-ts (Tailscale)
|
||||
## Configuration
|
||||
|
||||
- Runs Tailscale VPN client
|
||||
- Image: tailscale/tailscale:latest
|
||||
- Container name: homepage-ts
|
||||
- Hostname: homepage
|
||||
- Requires NET_ADMIN and SYS_MODULE capabilities
|
||||
- Persists state in ./tailscale/tailscale-data
|
||||
- Uses configuration from ./tailscale/config
|
||||
### Switching Serve Configs
|
||||
|
||||
### homepage
|
||||
| Environment | File to use | Notes |
|
||||
|-------------------|--------------------------------------|-------|
|
||||
| Tailscale (default) | `tailscale/config/serve.json` | Supports HTTP + HTTPS with certs |
|
||||
| Headscale | `tailscale/config/serve.headscale.json` | HTTP only |
|
||||
|
||||
- Runs Homepage dashboard
|
||||
- Image: ghcr.io/gethomepage/homepage:latest
|
||||
- Container name: homepage
|
||||
- Configuration stored in ./homepage/config
|
||||
- Uses Tailscale's network stack (no direct port mapping)
|
||||
- Depends on homepage-ts service
|
||||
After changing the serve config, restart the sidecar:
|
||||
```bash
|
||||
docker compose restart homepage-ts
|
||||
```
|
||||
|
||||
## Usage
|
||||
When the sidecar restarts, restart the homepage container too so it re-joins the new network namespace:
|
||||
```bash
|
||||
docker compose restart homepage
|
||||
```
|
||||
|
||||
- After starting the services your service should be available via tailnet at `https://homepage.{{YOUR_TAILNET_DOMAIN}}.ts.net` ie `https://homepage.tail12345.ts.net/`
|
||||
- To manually get the Tailscale IP/hostname of your container:
|
||||
```bash
|
||||
docker logs homepage-ts
|
||||
```
|
||||
Look for the Tailscale IP address in the logs.
|
||||
### Dashboard Configuration
|
||||
|
||||
## Optional Features
|
||||
Homepage reads its dashboard layout from YAML files in `./homepage/config/`:
|
||||
|
||||
- Uncomment the Docker socket volume mapping in the Homepage service to enable Docker integrations:
|
||||
```yaml
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
- Uncomment and adjust the ports mapping if you need direct access (without Tailscale):
|
||||
```yaml
|
||||
ports:
|
||||
- 3000:3000
|
||||
```
|
||||
- Stopping the Services
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
- `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.
|
||||
|
||||
## Troubleshooting
|
||||
- Check container logs:
|
||||
```bash
|
||||
docker logs homepage-ts
|
||||
docker logs homepage
|
||||
```
|
||||
- Ensure your Tailscale auth key is valid and not expired
|
||||
- Verify the configuration files have proper permissions
|
||||
- Make sure required directories exist before starting
|
||||
## Notes
|
||||
- The Homepage service uses the Tailscale service's network stack via network_mode: service:homepage-ts
|
||||
- Direct port mapping is disabled by default as Tailscale handles the networking
|
||||
- Services restart automatically unless explicitly stopped
|
||||
- For more information:
|
||||
- Tailscale documentation: https://tailscale.com/kb/
|
||||
- Homepage documentation: https://gethomepage.dev/
|
||||
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user