From 5be51c1adae2aa117f228de35e6f00c389d03b8a Mon Sep 17 00:00:00 2001 From: kappa Date: Thu, 11 Sep 2025 10:22:18 +0900 Subject: [PATCH] docs: Add CLAUDE.md for Claude Code integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create comprehensive guide for future Claude Code instances working with this nginx-proxy-manager automation project. Includes: - System architecture overview (Podman + Quadlet + systemd) - Essential development and diagnostic commands - Critical configuration file locations and dependencies - Troubleshooting patterns for rootless container deployment - Security model and performance characteristics Focus on operational knowledge specific to this rootless container setup with privileged port binding and systemd auto-start. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f25d9c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,151 @@ +# 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 \ No newline at end of file