# 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.