# homepage Stack
description: A NetGrimoire service providing a web interface for accessing various features.

---
# homepage

## Overview
The `homepage` stack is a Docker Swarm-based service that provides a web interface for accessing various features in NetGrimoire. It consists of a single container running the `ghcr.io/gethomepage/homepage:latest` image, which exposes port 3000.

## Architecture
| Service | Image | Port | Role |
|---------|-----|-----|-----|
| Host    | docker4 |        | Docker Swarm Manager |
| Network  | netgrimoire | Internal only | Caddy Reverse Proxy |
| Exposed via | homepage.netgrimoire.com | Homepage group |
| Homepage group | kuma.homepage.http.name="Homepage", caddy=homepage.netgrimoire.com, caddy.reverse_proxy=homepage:3000 |

---

## Build & Configuration

### Prerequisites
No specific prerequisites are required for this stack.

### Volume Setup
```bash
mkdir -p /DockerVol/homepage/config
chown -R 1001:1001 /DockerVol/homepage/config
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
HOMEPAGE_ALLOWED_HOSTS=homepage.netgrimoire.com,glance.netgrimoire.com,homepage:3000,192.168.5.10:3056
HOMEPAGE_VAR_MAILCOW_KEY=9C7D23-4BCD14-2CA4D3-D8B5D5-59CB4A
HOMEPAGE_VAR_DNS_TOKEN=2f6c5b9b331c2b84
HOMEPAGE_VAR_OPNSENSE_USER=xSt1B1fndmzFQ3x823cKO2/H8/oZOC2BcA0wgtetIwR1CbtRAuHUQoWkiwjskqNkFFJwSaBPi46Vvz6z
HOMEPAGE_VAR_OPNSENSE_PASS=8OBBLQWxz6Wdz/NOFkhmg/0kzAIf2gXCFpFOLbcLmZ83lRyBhk4Ev593omDLYm/Av+AC+mDPlA8Wzkfz
HOMEPAGE_VAR_IMMICH_KEY=yawqFGqMOQnGIXLmYr2daygAFFIHMaTnqOWNwZhm8SU
```

### Deploy
```bash
cd services/swarm/stack/homepage
set -a && source .env && set +a
docker stack config --compose-file homepage-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml homepage
rm resolved.yml
docker stack services homepage
```

### First Run
No specific post-deploy steps are required for this service.

---

## User Guide

### Accessing homepage
| Service | URL | Purpose |
|---------|-----|---------|
| Homepage | http://homepage:3000 | Web interface for accessing various features |

### Primary Use Cases
To access the web interface, navigate to `http://homepage:3000` in a web browser.

### NetGrimoire Integrations
This service integrates with other services in NetGrimoire, such as Kuma and Authentik.

---

## Operations

### Monitoring
```bash
docker stack services homepage
docker service logs -f homepage
```

### Backups
Critical: The `/DockerVol/homepage/config` volume should be backed up regularly to ensure data integrity.

### Restore
```bash
cd services/swarm/stack/homepage
./deploy.sh
```

---

## Common Failures
| Failure Mode | Symptoms | Cause | Fix |
|-------------|----------|------|-----|
| Service Not Available | Homepage not accessible | Docker Swarm not deployed or services not running | Check Docker Swarm logs and service status |
| Caddy Configuration Errors | Caddy errors in logs | Invalid Caddy configuration or incorrect environment variables | Review Caddy configuration and environment variables |

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-27 | 0b974044 | Initial deployment |
| 2026-04-27 | 340b5fcf | Updated Docker Swarm configuration |
| 2026-04-27 | bb59fec1 | Added Caddy reverse proxy configuration |
| 2026-04-06 | 7a9eb96d | Updated environment variables and Caddy configuration |
| 2026-04-06 | fb7d3f0d | Fixed Docker Swarm deployment issue |

<Generated by Gremlin on 2026-04-28T01:15:54.819Z>
<Source: swarm/homepage.yaml>
<Review User Guide and Changelog sections>