# homepage Stack

description: NetGrimoire Homepage service

---
title: homepage Stack

## Overview
The `homepage` stack provides a web interface for accessing the NetGrimoire dashboard. The stack consists of a single service, which is deployed on the `znas` node.

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- Exposed via: `homepage.netgrimoire.com`
- **Homepage group:** homepage

---
title: Build & Configuration

### Prerequisites
Ensure that the `.env` file is present and sourced in the deploy script.

### Volume Setup
```bash
mkdir -p /DockerVol/homepage/config
chown -R nobody:nobody /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
```

---
title: First Run

Perform the following steps after deploying the service:
```bash
# Initialize database and load data
npm run init db
npm run load-data
```

---
title: User Guide

### Accessing Homepage
| Service | URL | Purpose |
- **Host:** `homepage.netgrimoire.com`
- **Port:** `3000` or `3056` (via reverse proxy)

### Primary Use Cases
Access the NetGrimoire dashboard to view and manage services, settings, and data.

### NetGrimoire Integrations
The `homepage` stack integrates with other services in the NetGrimoire network via environment variables and labels.

---
title: Operations

### Monitoring
[kuma monitors from kuma.* labels]
```bash
docker stack services homepage
kuma logs -f
```

### Backups
Critical data is stored on the `/DockerVol/homepage/data` mount point. This directory should be backed up regularly to prevent data loss.

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

---
title: Common Failures

| Symptom | Cause | Fix |
|---------|-------|-----|
- Service not responding
  - Cause: Container is not running or has crashed.
  - Fix: Check container logs and restart the service if necessary.

- Reverse proxy issues
  - Cause: Caddy configuration is incorrect.
  - Fix: Review Caddy configuration files and update as needed.

- Data corruption
  - Cause: Database or file system issues.
  - Fix: Run database and file system checks to identify and correct any errors.