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>
This commit is contained in:
2025-08-06 17:24:11 +02:00
parent 7ef8c62324
commit f7b5d26eab
10 changed files with 1706 additions and 12 deletions

95
CLAUDE.md Normal file
View File

@@ -0,0 +1,95 @@
# 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
```bash
# 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
```bash
# 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
```bash
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
1. Edit files in `config/` directory
2. Test locally when possible
3. Deploy to target locations with sudo commands included in file headers
4. Update documentation status in `docs/services.md`
5. 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