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.

Prerequisites

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

Project Structure

ts-homepage/
├── docker-compose.yml
├── tailscale/
│   ├── tailscale-data/  # Persistent Tailscale state
│   └── config/         # Tailscale configuration files
└── homepage/
    └── config/         # Homepage configuration files

Setup Instructions

Clone the Repository

git clone https://gitea.damconsulting.llc/DAM/ts-homepage.git
cd ts-homepage

Create Required Directories

mkdir -p tailscale/tailscale-data tailscale/config homepage/config

Configure Tailscale
- Replace {{YOUR_TAILSCALE_AUTHKEY}} in the docker-compose.yml with your actual Tailscale auth key
- 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
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: "*")
Start the Services
```
docker compose up -d
```

Services

homepage-ts (Tailscale)

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

homepage

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

Usage

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:
```
docker logs homepage-ts
```
Look for the Tailscale IP address in the logs.

Optional Features

Uncomment the Docker socket volume mapping in the Homepage service to enable Docker integrations:
```
- /var/run/docker.sock:/var/run/docker.sock
```
Uncomment and adjust the ports mapping if you need direct access (without Tailscale):
```
ports:
- 3000:3000
```
Stopping the Services
```
docker compose down
```

Troubleshooting

Check container logs:

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/