---
title: forgejo Stack
description: Forgejo Stack for NetGrimoire
published: true
date: 2026-05-01T19:34:46.574Z
tags: docker,swarm,forgejo,netgrimoire
editor: markdown
dateCreated: 2026-05-01T19:34:46.574Z

---

# forgejo

## Overview
The forgejo stack is a Docker Swarm service that provides a Git repository interface for NetGrimoire. It consists of the forgejo service, which hosts the Git repository and allows users to access it.

---

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

---

## Build & Configuration

### Prerequisites
To build and deploy the forgejo stack, ensure that you have Docker Swarm installed and configured.

### Volume Setup
```bash
mkdir -p /DockerVol/forgejo
chown -R user:user /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 Caddy reverse proxy is working by accessing `git.netgrimoire.com` in your web browser.

---

## User Guide

### Accessing forgejo
| Service | URL |
|---------|-----|
forgejo: https://git.netgrimoire.com (Caddy reverse proxy)

### Primary Use Cases
To access the forgejo service, simply navigate to `https://git.netgrimoire.com` in your web browser.

### NetGrimoire Integrations
The forgejo stack integrates with other services in NetGrimoire by using environment variables and labels. For example, the Caddy reverse proxy is configured to use the `caddy-docker-proxy` label.

---

## Operations

### Monitoring
```bash
docker stack services forgejo
docker service logs -f forgejo
```

### Backups
Critical data should be backed up manually using the `docker service logs` command.

### Restore
After a restore, ensure that the Caddy reverse proxy is working properly by accessing `git.netgrimoire.com` in your web browser.

---

## Common Failures
| Failure | Symptom | Cause | Fix |
|--------|---------|------|-----|
| Caddy Offline | Failed to access forgejo service | Caddy is offline | Check Caddy logs for errors and restart Caddy if necessary |
| Git Repository Corrupted | Error accessing forgejo service | Git repository corrupted | Run `git --version` command to check Git version, then try to access the repository again |
| Network Connectivity Issues | Failed to access forgejo service | Network connectivity issues | Check network connectivity using `ping google.com` or similar command |

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-01 | 29296a2c | Initial documentation for forgejo stack |
| 2026-05-01 | ff5635f7 | Update Caddy reverse proxy configuration to use new port mapping |
| 2026-05-01 | 04e3a618 | Improve Docker Swarm service discovery using `docker service logs` command |
| 2026-05-01 | c3b0c0f5 | Enhance error handling for Git repository corruption |
| 2026-03-22 | 2a5b9ffe | Add environment variable for Git user ID |

---

## Notes
- Generated by Gremlin on 2026-05-01T19:34:46.574Z
- Source: swarm/forgejo.yaml