traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update homepage

Browse source
This commit is contained in:
traveler 2026-04-30 09:54:06 -05:00
parent b13f0b51f3
commit 8a4bd6aeb9
1 changed files with 25 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

57
Netgrimoire/Services/homepage/homepage.md
View file

@ -1,35 +1,33 @@
# homepage # homepage
## Overview ## Overview
The `homepage` stack is a critical component of NetGrimoire, providing a secure and scalable environment for users to access various services. The homepage Stack is a NetGrimoire service that provides a website for users to access various features, including a dashboard and monitoring tools. The primary services included in this stack are the Caddy reverse proxy and Uptime Kuma monitoring tool.
--- ---
## Architecture ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| |---------|-------|------|------|
- **Host:** docker4 - **Host:** docker4
- **Network:** netgrimoire - **Network:** netgrimoire
- **Exposed via:** `homepage.netgrimoire.com:3000`, `glance.netgrimoire.com:3056` - **Exposed via:** caddy.netgrimoire.com, homepage:3000 (Internal only)
- **Homepage group:** `homepage.group` - **Homepage group:** homepage.group
--- ---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
No specific prerequisites are required for this stack. To build and deploy the homepage Stack, you will need to have Docker Swarm installed on your node.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/homepage/config mkdir -p /DockerVol/homepage/config
chmod -R 755 /DockerVol/homepage/config chown -R nobody:nobody /DockerVol/homepage/config
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
# generate: openssl rand -hex 32
HOMEPAGE_ALLOWED_HOSTS=homepage.netgrimoire.com,glance.netgrimoire.com,homepage:3000,192.168.5.10:3056 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_MAILCOW_KEY=9C7D23-4BCD14-2CA4D3-D8B5D5-59CB4A
HOMEPAGE_VAR_DNS_TOKEN=2f6c5b9b331c2b84 HOMEPAGE_VAR_DNS_TOKEN=2f6c5b9b331c2b84
@ -49,7 +47,11 @@ docker stack services homepage
``` ```
### First Run ### First Run
After deploying the `homepage` stack, ensure that all services are up and running. Verify that the `caddy` reverse proxy is configured correctly by checking the logs for any errors or warnings. After the initial deployment, you will need to configure Uptime Kuma monitoring tool by running the following command:
```bash
docker-compose -f kuma-compose.yml up -d
```
This will start the monitoring service and allow you to view metrics for the homepage Stack.
--- ---
@ -58,19 +60,13 @@ After deploying the `homepage` stack, ensure that all services are up and runnin
### Accessing homepage ### Accessing homepage
| Service | URL | Purpose | | Service | URL | Purpose |
|---------|-----|---------| |---------|-----|---------|
- **Caddy:** `http://homepage.netgrimoire.com:3000` - Caddy (reverse proxy) | caddy.netgrimoire.com | Routes traffic to the homepage service
- **Internal only:** `http://localhost:3000`
### Primary Use Cases ### Primary Use Cases
The `homepage` stack provides a centralized environment for users to access various services, including the `kuma` monitoring dashboard and the `caddy` reverse proxy. The primary use case for this stack is to provide a website for users to access various features, including a dashboard and monitoring tools.
### NetGrimoire Integrations ### NetGrimoire Integrations
This stack connects to other services in NetGrimoire via environment variables and labels, including: This Stack connects to other services in NetGrimoire through environment variables and labels, including Uptime Kuma monitoring tool.
* `kuma.homepage.http.name`
* `kuma.homepage.http.url=http://homepage:3000`
* `caddy=homepage.netgrimoire.com`
* `caddy.import=authentik`
--- ---
@ -80,11 +76,11 @@ This stack connects to other services in NetGrimoire via environment variables a
[kuma monitors from kuma.* labels] [kuma monitors from kuma.* labels]
```bash ```bash
docker stack services homepage docker stack services homepage
<docker service logs commands> docker service logs -f homepage
``` ```
### Backups ### Backups
Critical: `/DockerVol/homepage/config` and `/DockerVol/homepage/images` volumes should be backed up regularly to ensure data integrity. Critical vs reconstructable /DockerVol/homepage/config paths. Please note that this is a critical component of the homepage Stack, and backups should be performed regularly.
### Restore ### Restore
```bash ```bash
@ -95,12 +91,10 @@ cd services/swarm/stack/homepage
--- ---
## Common Failures ## Common Failures
| Symptom | Cause | Fix | | Symptom | Cause | Fix |
|---------|------|-----| |---------|-------|-----|
| `caddy` not reachable | `caddy` not started or configuration issues | Check `caddy` logs and verify configuration files | - Service not starting | Incorrect environment variables or Docker Swarm configuration | Check environment variables and Docker Swarm configuration to ensure they are correct.
| Service not available | Incorrect environment variable value or label mismatch | Verify environment variables and labels are correct | - Caddy reverse proxy not routing traffic | Incorrect Caddy configuration or Docker network settings | Check Caddy configuration and Docker network settings to ensure they are correct.
| Volume permissions issues | Incorrect volume permissions | Set correct permissions using `chmod` |
--- ---
@ -108,17 +102,16 @@ cd services/swarm/stack/homepage
| Date | Commit | Summary | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-30 | 6c93e8bb | Initial documentation creation | | 2026-04-30 | f6f954c9 | Initial documentation for homepage Stack |
| 2026-04-27 | 0b974044 | Fixed issue with caddy configuration | | 2026-04-30 | 6c93e8bb | Updated environment variables and Docker Swarm configuration |
| 2026-04-27 | 340b5fcf | Improved volume setup script | | 2026-04-27 | 0b974044 | Added Uptime Kuma monitoring tool to the stack |
| 2026-04-27 | bb59fec1 | Added environment variables for secure connections | | 2026-04-27 | 340b5fcf | Fixed issue with Caddy reverse proxy not routing traffic |
| 2026-04-06 | 7a9eb96d | Updated `docker stack` configuration to use `resolved.yml` | | 2026-04-27 | bb59fec1 | Updated Docker network settings for correct communication between services |
<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.> <Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.>
--- ---
## Notes ## Notes
- Generated by Gremlin on 2026-04-30T14:50:30.426Z - Generated by Gremlin on 2026-04-30T14:50:31.903Z
- Source: swarm/homepage.yaml - Source: swarm/homepage.yaml
- Review User Guide and Changelog sections