Files

Arpad Krejczinger f7b5d26eab Reorganize repository structure and add configuration management

- Create organized directory structure:
  - docs/ for all documentation files
  - config/ for deployment configurations and scripts
- Add CLAUDE.md with project architecture and development workflow
- Update README.md with new structure and current status
- Move all documentation to docs/ directory
- Organize Docker and Nginx configurations under config/

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-06 17:24:11 +02:00

3.4 KiB

Raw Blame History

CLAUDE.md

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

Project Overview

This is a personal homelab setup repository documenting the migration from cloud services to self-hosted solutions on a ThinkPad running Arch Linux. The project uses Docker for containerized services behind an Nginx reverse proxy.

Architecture

Network Infrastructure

Domain: ak-homelab.duckdns.org (DuckDNS dynamic DNS)
Static IP: 192.168.0.100 (dual interface: ethernet enp4s0, WiFi wlp1s0)
SSH: Custom port 2222 for system access
Reverse Proxy: Nginx for path-based routing to services

Service Architecture

Internet → Router → Nginx (80/443) → Services
                 → SSH (2222) → System
                 → Gitea SSH (2223) → Git operations

Current Services:

Gitea Git server: Docker container on port 3000, accessible via /gitea/ path
Nginx: Reverse proxy routing to ak-homelab.duckdns.org/servicename/

Configuration Management

All configurations are version controlled in the config/ directory:

config/docker/gitea/: Gitea container setup and deployment scripts
config/nginx/: Reverse proxy configurations
config/scripts/: Utility scripts for system maintenance

Configuration files include deployment instructions in comments showing target locations (e.g., /opt/docker/gitea/, /etc/nginx/sites-available/).

Key Commands

Docker Service Management

# Gitea operations (from /opt/docker/gitea/)
docker-compose logs gitea        # View logs
docker-compose down             # Stop
docker-compose up -d            # Start
docker-compose pull && docker-compose up -d  # Update

# Deploy from repo
sudo cp config/docker/gitea/docker-compose.yml /opt/docker/gitea/

Nginx Operations

# Deploy configuration
sudo cp config/nginx/homelab.conf /etc/nginx/sites-available/homelab
sudo ln -s /etc/nginx/sites-available/homelab /etc/nginx/sites-enabled/homelab

# Management
sudo nginx -t                   # Test config
sudo systemctl reload nginx     # Reload
sudo systemctl status nginx     # Status

SSL Certificate Management

sudo certbot --nginx -d ak-homelab.duckdns.org
sudo systemctl enable certbot.timer  # Auto-renewal

Development Workflow

Task Tracking

Use TODO.md for centralized task management organized by category (Network & Security, Git & Development, System Configuration, etc.). Mark completed items and update status in documentation.

Configuration Changes

Edit files in config/ directory
Test locally when possible
Deploy to target locations with sudo commands included in file headers
Update documentation status in docs/services.md
Commit changes with logical separation

Documentation Structure

docs/: Technical documentation for setup procedures
README.md: Overview and current status
TODO.md: Active task tracking
Configuration files self-document deployment locations in headers

Network Configuration Notes

System uses dual ethernet ports (enp3s0f0, enp4s0) - stick to enp4s0 consistently
Port conflicts: SSH (2222), Gitea SSH (2223), Gitea Web (3000)
Router forwarding: HTTP (80), HTTPS (443), SSH (2222), Git SSH (2223)

Service URLs

Local access: http://192.168.0.100/servicename/
External access: http://ak-homelab.duckdns.org/servicename/
Gitea SSH: ssh://git@ak-homelab.duckdns.org:2223

3.4 KiB Raw Blame History