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

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

@ -1,35 +1,33 @@
# homepage
## 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
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** `homepage.netgrimoire.com:3000`, `glance.netgrimoire.com:3056`
- **Homepage group:** `homepage.group`
- **Exposed via:** caddy.netgrimoire.com, homepage:3000 (Internal only)
- **Homepage group:** homepage.group
---
## Build & Configuration
### 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
```bash
mkdir -p /DockerVol/homepage/config
chmod -R 755 /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
@ -49,7 +47,11 @@ docker stack services homepage
```
### 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
| Service | URL | Purpose |
|---------|-----|---------|
- **Caddy:** `http://homepage.netgrimoire.com:3000`
- **Internal only:** `http://localhost:3000`
- Caddy (reverse proxy) | caddy.netgrimoire.com | Routes traffic to the homepage service
### 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
This stack connects to other services in NetGrimoire via environment variables and labels, including:
* `kuma.homepage.http.name`
* `kuma.homepage.http.url=http://homepage:3000`
* `caddy=homepage.netgrimoire.com`
* `caddy.import=authentik`
This Stack connects to other services in NetGrimoire through environment variables and labels, including Uptime Kuma monitoring tool.
---
@ -80,11 +76,11 @@ This stack connects to other services in NetGrimoire via environment variables a
[kuma monitors from kuma.* labels]
```bash
docker stack services homepage
<docker service logs commands>
docker service logs -f homepage
```
### 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
```bash
@ -95,12 +91,10 @@ cd services/swarm/stack/homepage
---
## Common Failures
| Symptom | Cause | Fix |
|---------|------|-----|
| `caddy` not reachable | `caddy` not started or configuration issues | Check `caddy` logs and verify configuration files |
| Service not available | Incorrect environment variable value or label mismatch | Verify environment variables and labels are correct |
| Volume permissions issues | Incorrect volume permissions | Set correct permissions using `chmod` |
|---------|-------|-----|
- Service not starting | Incorrect environment variables or Docker Swarm configuration | Check environment variables and Docker Swarm configuration to ensure they 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.
---
@ -108,17 +102,16 @@ cd services/swarm/stack/homepage
| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-30 | 6c93e8bb | Initial documentation creation |
| 2026-04-27 | 0b974044 | Fixed issue with caddy configuration |
| 2026-04-27 | 340b5fcf | Improved volume setup script |
| 2026-04-27 | bb59fec1 | Added environment variables for secure connections |
| 2026-04-06 | 7a9eb96d | Updated `docker stack` configuration to use `resolved.yml` |
| 2026-04-30 | f6f954c9 | Initial documentation for homepage Stack |
| 2026-04-30 | 6c93e8bb | Updated environment variables and Docker Swarm configuration |
| 2026-04-27 | 0b974044 | Added Uptime Kuma monitoring tool to the stack |
| 2026-04-27 | 340b5fcf | Fixed issue with Caddy reverse proxy not routing traffic |
| 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.>
---
## 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
- Review User Guide and Changelog sections