Arpad Krejczinger
7868c7763b
- Add AI voice assistant to goals and current status - Include voice assistant in documentation structure - Update repository structure diagram - Add voice server commands to CLAUDE.md - Include voice assistant service URLs and management commands 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# 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
|
|
- **Voice Assistant**: http://127.0.0.1:8880 (local TTS server)
|
|
|
|
### Voice Assistant Commands
|
|
```bash
|
|
# Enable voice mode (starts server and configures voice-mode)
|
|
./scripts/enable-voice.sh
|
|
|
|
# Disable voice mode (stops server)
|
|
./scripts/disable-voice.sh
|
|
|
|
# Manual voice server management
|
|
cd voice-server
|
|
poetry run voice-server # Start server
|
|
poetry install # Install dependencies
|
|
poetry run pytest # Run tests
|
|
|
|
# Test TTS directly
|
|
curl -X POST "http://127.0.0.1:8880/v1/audio/speech" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"input": "Hello world!", "voice": "ryan"}' \
|
|
--output test.wav
|
|
``` |