---
title: homepage Stack
description: Migration to swarm configuration
published: true
date: 2026-04-07T02:50:56.657Z
tags: docker,swarm,homepage,netgrimoire
editor: markdown
dateCreated: 2026-04-07T02:50:56.657Z
---

# homepage

## Overview
The homepage stack is a Docker Swarm configuration for deploying the Get Homepage service in NetGrimoire. It consists of a single container running the ghcr.io/gethomepage/homepage:latest image.

---

## Architecture
| Service | Image | Port | Role |
|---------|-----|-----|------|
- **Host:** docker4
- **Network:** netgrimoire
- Exposed via: homepage.netgrimoire.com, glance.netgrimoire.com (via Caddy reverse proxy)
- Homepage group: homepage

---

## Build & Configuration

### Prerequisites
None

### Volume Setup
```bash
mkdir -p /DockerVol/homepage/config
chown -R $USER:$GROUP /DockerVol/homepage/config
```

### Environment Variables
```bash
# generate: openssl rand -hex 32 for HOMEPAGE_VAR_OPNSENSE_PASS and HOMEPAGE_VAR_IMMICH_KEY
HOMEPAGE_ALLOWED_HOSTS=homepage.netgrimoire.com,glance.netgrimoire.com
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 steps required, but ensure the container is running and Caddy is configured correctly.

---

## User Guide

### Accessing homepage
| Service | URL | Purpose |
- **Caddy reverse proxy:** http://homepage:3000
- **Internal service:** Not exposed via internal network

### Primary Use Cases
Deploying a simple web server with a few environment variables set.

### NetGrimoire Integrations
This stack integrates with the following services:
- Caddy for reverse proxy and HTTPS termination
- Uptime Kuma for monitoring
- Homepage group for routing traffic to this service

---

## Operations

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

### Backups
Critical backups should be made of the /DockerVol/homepage/config directory.

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

---

## Common Failures
| Symptom | Cause | Fix |
- **Service not starting:** Insufficient resources or incorrect port mapping.
- **Caddy configuration issues:** Ensure Caddy is configured correctly and logging is enabled.
- **Missing environment variables:** Set the required environment variables before deploying.

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-06 | 7a9eb96d | Initial configuration |
| 2026-04-06 | fb7d3f0d | Fixed Caddy reverse proxy URL |
| 2026-04-06 | e6f86e24 | Added environment variables for OPNSENSE_USER and IMMICH_KEY |
| 2026-04-06 | 5db4fdd9 | Updated Docker image to latest version |
| 2026-03-22 | c4ac5abf | Initial documentation |

---

## Notes
- Generated by Gremlin on 2026-04-07T02:50:56.657Z
- Source: swarm/homepage.yaml
- Review User Guide and Changelog sections