134 lines
3.5 KiB
Markdown
134 lines
3.5 KiB
Markdown
# Homepage
|
|
|
|
Self-hosted start page / dashboard using [Homepage](https://gethomepage.dev/) via Docker Compose.
|
|
|
|
---
|
|
|
|
## Repository Contents
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `docker-compose.yaml` | Homepage service definition |
|
|
|
|
Configuration files live outside this repo at `/etc/homepage/` on the host.
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
- **Homepage** - `ghcr.io/gethomepage/homepage:latest`
|
|
- **Docker socket** - mounted for live container status widgets
|
|
- **SMB share** - `/smb` mounted into the container for any assets served from network storage
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Docker + Docker Compose installed
|
|
- `/etc/homepage/` directory created on the host with your config files in place
|
|
- `/etc/homepage/images/` directory created for custom images/icons
|
|
- `/etc/homepage/.env` file created (see below)
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### 1. Create the config directory
|
|
|
|
```bash
|
|
mkdir -p /etc/homepage/images
|
|
```
|
|
|
|
### 2. Create the `.env` file
|
|
|
|
Homepage reads environment variables from `/etc/homepage/.env`. At minimum create an empty file so the container starts:
|
|
|
|
```bash
|
|
touch /etc/homepage/.env
|
|
```
|
|
|
|
API keys for service widgets go here. Example:
|
|
|
|
```env
|
|
HOMEPAGE_VAR_SONARR_KEY=your_sonarr_api_key
|
|
HOMEPAGE_VAR_RADARR_KEY=your_radarr_api_key
|
|
HOMEPAGE_VAR_TAUTULLI_KEY=your_tautulli_api_key
|
|
```
|
|
|
|
Variables prefixed with `HOMEPAGE_VAR_` are available in your `services.yaml` as `{{HOMEPAGE_VAR_SONARR_KEY}}`.
|
|
|
|
### 3. Populate config files
|
|
|
|
Homepage is configured entirely through YAML files in `/etc/homepage/`:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `settings.yaml` | Title, theme, color scheme, layout |
|
|
| `services.yaml` | Service tiles and widgets |
|
|
| `bookmarks.yaml` | Bookmark groups and links |
|
|
| `widgets.yaml` | Top-bar info widgets (search, date, resources) |
|
|
| `docker.yaml` | Docker socket integration config |
|
|
| `custom.css` | Optional style overrides |
|
|
| `custom.js` | Optional JS overrides |
|
|
|
|
See the [Homepage docs](https://gethomepage.dev/configs/) for full reference.
|
|
|
|
### 4. Start the stack
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Homepage will be available at `http://<host>:3000`.
|
|
|
|
---
|
|
|
|
## Ports
|
|
|
|
| Port (Host) | Port (Container) | Purpose |
|
|
|-------------|------------------|---------|
|
|
| `3000` | `3000` | Homepage web UI |
|
|
|
|
---
|
|
|
|
## Allowed Hosts
|
|
|
|
The `HOMEPAGE_ALLOWED_HOSTS` environment variable restricts which hostnames/IPs can serve the dashboard. Currently set to:
|
|
|
|
```
|
|
10.10.14.199:3000 (host IP)
|
|
home.wittenberger.us
|
|
home.wittenberger.local
|
|
```
|
|
|
|
Add or remove entries as needed when accessing from additional addresses.
|
|
|
|
---
|
|
|
|
## Volumes
|
|
|
|
| Host Path | Container Path | Purpose |
|
|
|-----------|----------------|---------|
|
|
| `/etc/homepage` | `/app/config` | All YAML config files and `.env` |
|
|
| `/etc/homepage/images` | `/app/public/images` | Custom images and icons |
|
|
| `/var/run/docker.sock` | `/var/run/docker.sock` | Docker integration (container status) |
|
|
| `/smb` | `/smb` | SMB share mount for network assets |
|
|
|
|
---
|
|
|
|
## Docker Integration
|
|
|
|
The Docker socket mount enables Homepage to display live container status on service tiles. Configure which containers to show in `/etc/homepage/docker.yaml` and reference them in `services.yaml` with a `docker` widget block.
|
|
|
|
> The Docker socket grants full Docker API access to the container. If this is a concern, consider fronting it with [Docker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy) to restrict permissions.
|
|
|
|
---
|
|
|
|
## Updating
|
|
|
|
```bash
|
|
docker compose pull
|
|
docker compose up -d
|
|
```
|
|
|
|
Config files in `/etc/homepage/` are unaffected by updates. |