# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This repository contains infrastructure automation for deploying nginx-proxy-manager using Podman + Quadlet on Debian systems. The architecture uses rootless containers with systemd-based auto-start for production proxy workloads.

## System Architecture

The system is built on a three-layer architecture:

1. **Container Runtime**: Podman 5.4.2 running in rootless mode with pasta networking
2. **Orchestration**: Quadlet (systemd generator) managing container lifecycle
3. **Host System**: Debian 13 with optimized kernel parameters for proxy workloads

**Key Design Decisions**:
- Rootless containers for security isolation
- Quadlet over Docker Compose for systemd integration
- Kernel tuning specifically for high-connection proxy scenarios
- Auto-start without user login via systemd lingering

## Development Commands

### Container Management
```bash
# Check service status
systemctl --user status nginx-proxy-manager.service

# View logs in real-time
journalctl --user -u nginx-proxy-manager.service -f

# Container inspection
podman ps
podman logs nginx-proxy-manager
podman exec -it nginx-proxy-manager /bin/bash

# Force container recreation
systemctl --user stop nginx-proxy-manager.service
systemctl --user start nginx-proxy-manager.service
```

### Quadlet Configuration Testing
```bash
# Validate Quadlet syntax before applying
/usr/libexec/podman/quadlet --user --dryrun

# Reload systemd after Quadlet changes
systemctl --user daemon-reload
```

### System Diagnostics
```bash
# Check kernel parameters are applied
cat /proc/sys/net/ipv4/ip_unprivileged_port_start  # should be 80
cat /proc/sys/vm/swappiness                        # should be 10
cat /proc/sys/net/core/somaxconn                   # should be 65535

# Verify port bindings
ss -tlnp | grep ':80\|:81\|:443'

# Check lingering status
loginctl show-user admin | grep Linger
```

## Critical Configuration Files

### Quadlet Container Definition
Location: `~/.config/containers/systemd/nginx-proxy-manager.container`

This file defines the container specification in systemd-native format. Key settings:
- `PublishPort=80:80` requires `net.ipv4.ip_unprivileged_port_start=80`
- `AutoUpdate=registry` enables automatic image updates
- `WantedBy=default.target` enables boot-time auto-start

### Kernel Tuning
Location: `/etc/sysctl.d/99-container-tuning.conf`

Critical for rootless containers binding to privileged ports:
- `net.ipv4.ip_unprivileged_port_start=80` - enables port 80 binding without root
- `net.core.somaxconn=65535` - handles high connection loads
- `vm.swappiness=10` - prioritizes memory over swap for container performance

### systemd Resource Limits
Location: `/etc/systemd/system.conf.d/limits.conf`

Extends default systemd limits for container workloads.

## Deployment Architecture

The system requires specific deployment order:

1. **Host Preparation**: Kernel tuning and systemd limits
2. **User Setup**: Enable lingering for non-interactive service start
3. **Quadlet Deployment**: Container definition and systemd integration
4. **Validation**: Auto-start testing via reboot

**Port Requirements**:
- Port 80: HTTP traffic
- Port 81: Admin interface
- Port 443: HTTPS traffic

## Network Architecture

Uses Podman's netavark backend with pasta for network isolation:
- Each container gets isolated network namespace
- Host ports mapped directly to container ports
- DNS forwarding through pasta daemon
- IPv6 disabled via container environment

## Troubleshooting Patterns

**Service Won't Start**: Usually kernel parameter issues
- Check `ip_unprivileged_port_start` setting
- Verify Quadlet syntax with dry-run

**Port Binding Failures**: Permission or conflict issues
- Check if ports are already in use: `ss -tlnp`
- Verify rootless port permissions

**Auto-start Failures**: systemd lingering issues
- Ensure lingering enabled: `loginctl enable-linger admin`
- Check service dependencies

## Performance Characteristics

System tuned for proxy workloads:
- **Boot Time**: ~40 seconds to full service availability
- **Connection Handling**: 65,535 concurrent connections (somaxconn limit)
- **Memory Usage**: Optimized for memory-over-swap with vm.swappiness=10
- **TCP Optimization**: Reduced connection timeouts for proxy traffic

## Security Model

**Rootless Isolation**:
- Container runs without root privileges on host
- User namespace isolation
- Limited blast radius for container escapes

**Network Security**:
- Pasta provides network namespace isolation
- Only explicitly mapped ports are accessible
- Container has no direct host network access

## Extension Points

The architecture supports:
- Multiple container deployment via additional `.container` files
- Load balancer integration through consistent port mapping
- Monitoring integration via systemd service dependencies
- Backup automation through volume management