stura-infra/hosts/git/README.md

# 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**:
- **Socket**: `/run/forgejo/forgejo.sock` (Unix socket)
- **Root URL**: https://git.adm.htw.stura-dresden.de
- **Protocol**: HTTP over Unix socket (Nginx handles TLS)

### 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](../../README.md) for deployment methods.

### Initial Installation

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

**Using container tarball:**
```bash
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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

- [Main README](../../README.md) - Deployment methods and architecture
- [Proxy README](../proxy/README.md) - How the central proxy routes traffic
- [Forgejo Documentation](https://forgejo.org/docs/latest/)
- [NixOS Forgejo Options](https://search.nixos.org/options?query=services.forgejo)