docs(gremlin): create forgejo

Netgrimoire/Services/forgejo/forgejo.md

@@ -0,0 +1,128 @@
+---
+title: forgejo Stack
+description: Forgejo web application stack in NetGrimoire
+published: true
+date: 2026-05-01T19:15:04.588Z
+tags: docker,swarm,forgejo,netgrimoire
+editor: markdown
+dateCreated: 2026-05-01T19:15:04.588Z
+---
+
+# forgejo
+
+## Overview
+The forgejo stack is a web application containerization service in NetGrimoire that exposes the Forgejo project to the public internet. The service provides access to the Forgejo repository and its associated assets.
+
+---
+## Architecture
+| Service | Image | Port | Role |
+|---------|-------|------|------|
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** `git.netgrimoire.com`, `http://forgejo:3000`
+- **Homepage group:** Applications
+
+---
+
+## Build & Configuration
+
+### Prerequisites
+- Docker installed on the swarm manager node.
+- Caddy and Uptime Kuma services running.
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/forgejo:/data
+chown -R user:group /DockerVol/forgejo
+```
+
+### Environment Variables
+```bash
+generate: openssl rand -hex 32
+USER_UID=1001
+USER_GID=998
+TZ=America/Chicago
+```
+
+### Deploy
+```bash
+cd services/swarm/stack/forgejo
+set -a && source .env && set +a
+docker stack config --compose-file forgejo-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml forgejo
+rm resolved.yml
+docker stack services forgejo
+```
+
+### First Run
+After the initial deployment, verify that the service is accessible at `http://forgejo:3000` and that Caddy's reverse proxy configuration is correct.
+
+---
+
+## User Guide
+
+### Accessing forgejo
+| Service | URL | Purpose |
+|---------|-----|---------|
+- Caddy (`git.netgrimoire.com`)
+- Uptime Kuma (`kuma.git.http.url=http://forgejo:3000`)
+
+### Primary Use Cases
+Forgejo can be used to access the Git repository and its associated assets.
+
+### NetGrimoire Integrations
+Forgejo integrates with NetGrimoire's monitoring services, including Caddy and Uptime Kuma.
+
+---
+
+## Operations
+
+### Monitoring
+-kuma monitors:
+- `kuma.git.http.name=Forgejo`
+- `kuma.git.http.url=http://forgejo:3000`
+
+```bash
+docker stack services forgejo
+docker service logs forgejo
+```
+
+### Backups
+Critical data stored in `/DockerVol/forgejo` and reconstructable from backups of the `image` container.
+
+### Restore
+```bash
+cd services/swarm/stack/forgejo
+./deploy.sh
+```
+
+---
+
+## Common Failures
+- Failure to start Caddy due to incorrect configuration.
+- Error logging from Uptime Kuma monitoring service.
+- Incorrectly set environment variables leading to service crashes.
+
+### Symptoms | Cause | Fix |
+|---------|------|-----|
+| Service not starting | Insufficient resources on the swarm node. | Ensure that sufficient resources are allocated to the swarm node. |
+| Monitoring errors | Invalid `kuma.git.http.url` configuration. | Verify and update `kuma.git.http.url` to point to the correct Forgejo service URL. |
+
+---
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-05-01 | 04e3a618 | Initial documentation deployment. |
+| 2026-05-01 | c3b0c0f5 | Minor bug fixes and documentation improvements. |
+| 2026-03-22 | 2a5b9ffe | Update `diun.enable` to `true` for better monitoring functionality. |
+| 2026-01-20 | 061ab0c2 | Initial deployment of the forgejo stack to Docker Swarm. |
+| 2026-01-10 | 1a374911 | Minor configuration adjustments and testing. |
+
+---
+
+## Notes
+- Generated by Gremlin on 2026-05-01T19:15:04.588Z
+- Source: swarm/forgejo.yaml
+- Review User Guide and Changelog sections