OVHserver/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a production infrastructure for AI-Impress, running on OVH server (ubuntu@51.89.231.46). The project uses a three-tier synchronization system:

1. Syncthing - Real-time bidirectional sync between Mac and server (10-30 seconds)
2. GitHub - Version control at git@github.com:SamoilenkoVadym/OVHserver.git
3. rsync - Full system backup for disaster recovery

Critical: You work with LOCAL files on Mac at /Volumes/SSD/Aimpress_Cloud_Prod/. Syncthing automatically syncs changes to the server. Never SSH into the server to make changes - always work locally.

Architecture

Directory Structure

/Volumes/SSD/Aimpress_Cloud_Prod/
├── opt/                      # Main services (synced to server /opt)
│   ├── 00-infrastructure/    # Core: Traefik, PostgreSQL, Redis, Vault, RabbitMQ, Loki
│   ├── 01-security/          # Authentik (SSO), Vaultwarden
│   ├── 02-core/              # n8n (automation), Evolution API (WhatsApp), Supabase
│   ├── 03-business/          # Odoo (ERP), Outline (wiki), Documenso, Wiki.js
│   ├── 04-tools/             # Portainer, Grafana, Prometheus, Uptime Kuma
│   ├── 05-backups/           # Backup scripts and data (NOT in Git)
│   └── 06-webflow/           # Landing pages
├── data/                     # Application data (synced to server /data)
├── home/                     # Ubuntu user files (synced to server /home/ubuntu)
└── mnt/                      # Mounted disks, backups, PostgreSQL data (synced to server /mnt)

Technology Stack

• Orchestration: Docker + Docker Compose (all services are containerized)
• Reverse Proxy: Traefik with automatic SSL (Let's Encrypt via Cloudflare)
• Databases: PostgreSQL (shared: postgres-main), Redis (redis-main), RabbitMQ
• Secrets: HashiCorp Vault (do NOT commit secrets)
• SSO: Authentik (Single Sign-On for all services)
• Monitoring: Prometheus + Grafana + Loki + Uptime Kuma
• Networks: Docker networks - traefik-public (external), database-internal (external)

Service Dependencies

Services MUST start in this order:

1. Traefik
2. PostgreSQL, Redis, RabbitMQ
3. Vault
4. Authentik
5. All other services

Common Development Commands

Docker Operations

# View running containers on server
ssh ubuntu@51.89.231.46 "docker ps"

# View logs for a container
ssh ubuntu@51.89.231.46 "docker logs <container_name>"

# Restart a service (via docker-compose)
ssh ubuntu@51.89.231.46 "cd /opt/<category>/<service> && docker compose restart"

# View service status
ssh ubuntu@51.89.231.46 "cd /opt/<category>/<service> && docker compose ps"

Managing Services

Each service has a docker-compose.yml file in its directory:

• Traefik: /opt/00-infrastructure/traefik/docker-compose.yml
• n8n-shared: /opt/02-core/n8n-shared/docker-compose.yml (includes 4 workers)
• Odoo: /opt/03-business/odoo/docker-compose.yml
• etc.

To deploy/update a service:

1. Edit the docker-compose.yml locally
2. Wait for Syncthing sync (10-30 seconds)
3. SSH to server: ssh ubuntu@51.89.231.46 "cd /opt/<path> && docker compose up -d"

Syncthing Operations

# Check Syncthing status on Mac
brew services list | grep syncthing

# Check Syncthing status on server
ssh ubuntu@51.89.231.46 "systemctl --user status syncthing"

# View sync size
du -sh /Volumes/SSD/Aimpress_Cloud_Prod/{opt,data,home,mnt}

Backup Operations

Backup scripts are in /opt/05-backups/scripts/:

• backup-full-enhanced.sh - Comprehensive backup with auto-discovery
• Scripts use Restic for incremental backups to Cloudflare R2
• See /opt/05-backups/SCRIPTS-REGISTRY.md for full script inventory

Git Workflow

Automated Git Hooks

pre-commit hook:

• Blocks commits containing .env, .key, .pem files
• Warns about potential secrets
• Can override with --no-verify (use carefully)

post-commit hook:

• Automatically pushes every commit to GitHub
• Works with main/master branches

Commit Message Format

<type>: <short description>

<optional detailed explanation>

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

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

Types:

• feat: - New feature
• fix: - Bug fix
• refactor: - Code refactoring
• docs: - Documentation
• chore: - Maintenance (configs, dependencies)
• perf: - Performance improvement

What NOT to Commit

Excluded via .gitignore:

• Dependencies: node_modules/, __pycache__/, venv/
• Secrets: .env, *.key, *.pem, credentials.json
• Backups: opt/05-backups/, *.sql.gz, *.tar.gz
• Data: **/docker-data/, **/volumes/
• Logs: *.log, logs/
• System: .DS_Store, .cache/

Key Configuration Patterns

Traefik Labels

Services use Traefik labels for routing:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.<service>.rule=Host(`<service>.ai-impress.com`)"
  - "traefik.http.routers.<service>.entrypoints=websecure"
  - "traefik.http.routers.<service>.tls.certresolver=cloudflare"
  - "traefik.http.services.<service>.loadbalancer.server.port=<port>"

Environment Variables

Services use .env files (NOT committed to Git):

• Database credentials reference shared PostgreSQL: postgres-main
• Redis credentials reference shared Redis: redis-main
• Passwords stored as ${VAR_NAME} in docker-compose.yml

Network Configuration

Services connect to external Docker networks:

networks:
  traefik-public:
    external: true
  database-internal:
    external: true

Important Architecture Notes

n8n Configuration

n8n-shared runs in queue mode with Redis:

• 1 main instance (n8n-shared) handles UI and API
• 4 worker instances process jobs from Redis queue
• Workers 1-2: High concurrency (20 jobs)
• Workers 3-4: Medium concurrency (15 jobs)
• Webhooks and OAuth endpoints bypass authentication for external access

Database Architecture

• Single PostgreSQL instance (postgres-main) serves multiple services
• Each service has its own database (e.g., n8n_shared, odoo_db)
• Connection via database-internal network
• Data stored in /mnt/psql-data/

SSL & Domain Management

All services use:

• Domain: *.ai-impress.com
• SSL via Traefik + Cloudflare DNS challenge
• Certificates stored in /opt/00-infrastructure/traefik/acme/

Workflow for Claude Code

When making changes:

1. Read local files from /Volumes/SSD/Aimpress_Cloud_Prod/
2. Edit files locally (never SSH to make changes)
3. Wait 10-30 seconds for Syncthing to sync to server
4. Commit with descriptive message using format above
5. Verify changes on server if needed (via SSH to view logs/status)

When adding new services:

1. Create directory in appropriate /opt/<category>/ folder
2. Create docker-compose.yml with Traefik labels
3. Create .env file (will be auto-ignored by Git)
4. Add to appropriate Docker networks
5. Document in project structure files
6. Test on server, then commit

Important Security Notes

• Never commit secrets - pre-commit hook will block .env files
• Use Vault for sensitive credentials when possible
• Authentik SSO protects most admin interfaces
• Traefik middleware can add authentication to services
• Database passwords are in .env files, referenced as ${VAR_NAME}

Troubleshooting

Service Won't Start

1. Check logs: ssh ubuntu@51.89.231.46 "docker logs <container>"
2. Verify networks exist: ssh ubuntu@51.89.231.46 "docker network ls"
3. Check if port is already in use
4. Verify Traefik is running first

Syncthing Issues

1. Check status on both Mac and server
2. View sync conflicts in Syncthing UI
3. Check .stignore for exclusion patterns
4. Verify folder permissions

Database Connection Issues

1. Ensure postgres-main container is running
2. Check database-internal network exists
3. Verify credentials in .env file
4. Check PostgreSQL logs: ssh ubuntu@51.89.231.46 "docker logs postgres-main"

Reference Documentation

• Detailed structure: .claude/project-structure.md
• Workflow details: .claude/workflow.md
• Backup scripts: opt/05-backups/SCRIPTS-REGISTRY.md
• Main README: README.md