StuRa/stura-infra
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
stura-infra/hosts/git/README.md
goeranh 9466ab3656
readme docs
2026-03-13 16:59:54 +01:00

5.5 KiB
Raw Permalink Blame History

Git Host - Forgejo

Forgejo git server at 141.56.51.7 running in an LXC container.

Overview

  • Hostname: git
  • FQDN: git.adm.htw.stura-dresden.de
  • IP Address: 141.56.51.7
  • Type: Proxmox LXC Container
  • Services: Forgejo, Nginx (reverse proxy), OpenSSH

Services

Forgejo

Forgejo is a self-hosted Git service (fork of Gitea) providing:

  • Git repository hosting
  • Web interface for repository management
  • Issue tracking
  • Pull requests
  • OAuth2 integration support

Configuration:

Nginx

Nginx acts as a reverse proxy between the network and Forgejo:

  • Receives HTTPS requests (TLS termination)
  • Forwards to Forgejo via Unix socket
  • Manages ACME/Let's Encrypt certificates
  • WebSocket support enabled for live updates

OAuth2 Auto-Registration

OAuth2 client auto-registration is enabled:

  • ENABLE_AUTO_REGISTRATION = true
  • REGISTER_EMAIL_CONFIRM = false
  • Username field: email

This allows users to register automatically via OAuth2 providers without manual approval.

Deployment

See the main README for deployment methods.

Initial Installation

Using nixos-anywhere:

nix run github:nix-community/nixos-anywhere -- --flake .#git --target-host root@141.56.51.7

Using container tarball:

nix build .#containers-git
scp result/tarball/nixos-system-x86_64-linux.tar.xz root@proxmox-host:/var/lib/vz/template/cache/
pct create 107 /var/lib/vz/template/cache/nixos-system-x86_64-linux.tar.xz \
  --hostname git \
  --net0 name=eth0,bridge=vmbr0,ip=141.56.51.7/24,gw=141.56.51.254 \
  --memory 2048 \
  --cores 2 \
  --rootfs local-lvm:8 \
  --unprivileged 1 \
  --features nesting=1
pct start 107

Updates

# From local machine
nixos-rebuild switch --flake .#git --target-host root@141.56.51.7

# Or use auto-generated script
nix run .#git-update

Post-Deployment Steps

After deploying for the first time:

  1. Access the web interface:

    https://git.adm.htw.stura-dresden.de

  2. Complete initial setup:

    • Create the first admin account via web UI
    • Configure any additional settings
    • Set up SSH keys for git access

  3. Configure OAuth2 (optional):

    • If using an external identity provider (e.g., authentik)
    • Add OAuth2 application in the provider
    • Configure OAuth2 settings in Forgejo admin panel
    • Auto-registration is already enabled in configuration

  4. Set up repositories:

    • Create organizations
    • Create repositories
    • Configure access permissions

Integration with Proxy

The central proxy at 141.56.51.1 handles:

  • SNI routing: Inspects TLS handshake and routes HTTPS traffic for git.adm.htw.stura-dresden.de
  • HTTP routing: Routes HTTP traffic based on Host header
  • ACME challenges: Forwards /.well-known/acme-challenge/ requests to this host for Let's Encrypt verification
  • Auto-redirect: Redirects HTTP to HTTPS (except ACME challenges)

This host handles its own TLS certificates via ACME. The proxy passes through encrypted traffic without decryption.

Troubleshooting

Forgejo socket permissions

If Forgejo fails to start or Nginx cannot connect:

# Check socket exists
ls -l /run/forgejo/forgejo.sock

# Check Forgejo service status
systemctl status forgejo

# Check Nginx service status
systemctl status nginx

# View Forgejo logs
journalctl -u forgejo -f

Solution: Ensure the Forgejo user has proper permissions and the socket path is correct in both Forgejo and Nginx configurations.

Nginx proxy configuration

If the web interface is unreachable:

# Check Nginx configuration
nginx -t

# View Nginx error logs
journalctl -u nginx -f

# Test socket connection
curl --unix-socket /run/forgejo/forgejo.sock http://localhost/

Solution: Verify the proxyPass directive in Nginx configuration points to the correct Unix socket.

SSH access issues

If git operations over SSH fail:

# Check SSH service
systemctl status sshd

# Test SSH connection
ssh -T git@git.adm.htw.stura-dresden.de

# Check Forgejo SSH settings
cat /var/lib/forgejo/custom/conf/app.ini | grep -A 5 "\[server\]"

Solution: Ensure SSH keys are properly added to user accounts and SSH daemon is running.

ACME certificate issues

If HTTPS is not working:

# Check ACME certificate status
systemctl status acme-git.adm.htw.stura-dresden.de

# View ACME logs
journalctl -u acme-git.adm.htw.stura-dresden.de -f

# Manually trigger certificate renewal
systemctl start acme-git.adm.htw.stura-dresden.de

Solution: Verify DNS points to proxy (141.56.51.1) and proxy is forwarding ACME challenges correctly.

Files and Directories

  • Configuration: /nix/store/.../forgejo/ (managed by Nix)
  • Data directory: /var/lib/forgejo/
  • Custom config: /var/lib/forgejo/custom/conf/app.ini
  • Repositories: /var/lib/forgejo/data/gitea-repositories/
  • Socket: /run/forgejo/forgejo.sock

Network

  • Interface: eth0 (LXC container)
  • IP: 141.56.51.7/24
  • Gateway: 141.56.51.254
  • Firewall: Ports 22, 80, 443 allowed

See Also