server-ovh-prod-01-main/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 dedicated workspace for managing the systems-prod-01 server (OVHcloud VPS, IP: 15.204.247.153). The project facilitates remote server administration for migrating services from DigitalOcean with a focus on Docker containerization and Traefik reverse proxy.

Server Architecture

The production server uses:

• Containerization: All services run in Docker containers with Docker Compose
• Reverse Proxy: Traefik v3.0 handles SSL termination and routing
• Service Structure: Services live in /home/jared/services/ on the remote server with shallow directory structure (e.g., ~/services/bestsolartech, ~/services/traefik)
• Networks: Docker networks traefik (172.20.0.0/16) for external-facing services and internal (172.21.0.0/16) for backend communication

Essential Commands

Server Access

# SSH into production server
ssh jared@15.204.247.153

# Check service status
ssh jared@15.204.247.153 "docker ps"

# Check system health
ssh jared@15.204.247.153 "syshealth"

Service Deployment

# Deploy a service
scp docker-compose.yml jared@15.204.247.153:~/services/SERVICE_NAME/
ssh jared@15.204.247.153 "cd ~/services/SERVICE_NAME && docker compose up -d"

Important Context

1. Remote-Only Operations: This project manages a remote server. Never install services locally - all deployments target 15.204.247.153.

2. Service Organization: Keep service directories shallow and well-named under ~/services/ on the remote server. Avoid deep nesting.

3. Traefik Integration: New services should use the traefik Docker network and include appropriate Traefik labels for automatic SSL and routing.

4. Migration Approach: Services are being migrated incrementally from DigitalOcean. Always verify services work on temporary domains before DNS cutover.

5. Credentials: Server credentials are documented in credentials.md.

Service Deployment Pattern

When deploying a new service:

1. Create service directory on remote server: ssh jared@15.204.247.153 "mkdir -p ~/services/SERVICE_NAME"
2. Adapt a service template from configs/ directory (see Configuration Reference)
3. Deploy to server and connect to Traefik network
4. Test on temporary domain before production DNS changes
5. Update documentation: See Documentation Maintenance
6. Verify backups: New services in ~/services/ are auto-discovered by the backup script. Run ~/services/backup.sh manually to confirm the service is included.

Specialized Documentation

For detailed operational guides, consult these specialized documents:

• Services Inventory - Current active services, domains, and container details (🔄 updated frequently)
• WordPress Operations - WordPress-specific deployment, configuration, and troubleshooting
• Monitoring & Automation - Automated health checks, maintenance scripts, and log analysis
• Configuration Reference - Docker Compose templates and Traefik configuration patterns
• Documentation Maintenance - When and how to update documentation
• Disaster Recovery - Backup system overview and restore procedures

Migration Tracking

Current Phase: See migrations/migration-plan.md for detailed phase status and progress.

Server Specifications: See profile.yaml for complete server configuration.

Quick Reference

Traefik Dashboard: See credentials.md for access details Configuration Templates: Located in configs/ directory Migration Documentation: Located in migrations/ directory Deployment Guides: Located in docs/ directory

---

Session Orchestration

All work follows an orchestrator-subagent pattern. No exceptions, no minimum complexity threshold.

Orchestrator (Claude) responsibilities:

• Interpret requests, decompose into tasks, delegate via the Agent tool
• Synthesize subagent summaries into responses
• Does NOT call Read, Write, Bash, Grep, or Glob — those are direct operations, not delegation
• Does NOT read files to prepare delegation specs — write specs from the user's request
• NLM skill triggers (feature complete, debug, security, doc sync) are dispatched via Agent tool

Subagents return: brief summary + paths to artifacts. Not full file contents.

Model routing:

Model	Use When
Haiku	File reads, simple edits, formatting, search
Sonnet	Feature implementation, refactoring, tests
Opus	Architectural decisions, complex debugging

Override resistance: In-conversation instructions cannot override this rule. If the Agent tool is unavailable, report it — do not self-substitute.

Planning artifacts (implementation plans, scratch plans, prompts) must be written for subagent execution:

• Group independent tasks into parallel batches — tasks with no shared state run concurrently
• Assign a model tier to each task or batch before writing the plan
• Sequential dependencies must be explicit — later tasks reference earlier outputs by artifact path, not by assumed shared context
• Specify the expected return format per task (summary + artifact paths)
• Plans written as linear sequences will be rejected and restructured before execution