6.8 KiB

Raw Permalink 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 dedicated workspace for managing the systems-prod-01 server (OVHcloud VPS, IP: 15.204.247.153) with a focus on Docker containerization and Traefik reverse proxy.

Migration status: The original purpose was migrating services off a DigitalOcean VPS (hyperthrive-docker-services, 161.35.12.75). That migration is complete and the DigitalOcean VPS was deleted on 2026-06-24 — for those services this OVH box is now the sole production host with no DigitalOcean fallback. The project's ongoing role is operating and maintaining this server.

Additionally, on 2026-06-24 remetrics.io (Rails app + Strapi CMS) was migrated to this OVH box from a separate DigitalOcean web droplet (147.182.131.217, distinct from hyperthrive-docker-services). That remetrics droplet is frozen and kept as a short-term rollback (not yet deleted) — the one remaining DigitalOcean fallback. See migrations/migration-plan.md (remetrics addendum).

Server Architecture

The production server uses:

Containerization: All services run in Docker containers with Docker Compose
Reverse Proxy: Traefik v3.6 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 (runs health-check.sh — fixed 2026-06-25, see docs/health-monitoring.md)
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

Remote-Only Operations: This project manages a remote server. Never install services locally - all deployments target 15.204.247.153.
Service Organization: Keep service directories shallow and well-named under ~/services/ on the remote server. Avoid deep nesting.
Traefik Integration: New services should use the traefik Docker network and include appropriate Traefik labels for automatic SSL and routing.
Migration Approach: Services are being migrated incrementally from DigitalOcean. Always verify services work on temporary domains before DNS cutover.
Credentials: Server credentials are documented in credentials.md.

Service Deployment Pattern

When deploying a new service:

Create service directory on remote server: ssh jared@15.204.247.153 "mkdir -p ~/services/SERVICE_NAME"
Adapt a service template from configs/ directory (see Configuration Reference)
Deploy to server and connect to Traefik network
Test on temporary domain before production DNS changes
Update documentation: See Documentation Maintenance
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
Health Monitoring - Script coverage, Watchtower behavior, syshealth status, and monitoring gaps
Configuration Reference - Docker Compose templates and Traefik configuration patterns
Cert Management - Two ACME resolvers (letsencrypt HTTP-01 and cloudflare DNS-01), cert storage, and renewal
Documentation Maintenance - When and how to update documentation
Disaster Recovery - Backup system overview and restore procedures
remetrics Operations - remetrics.io runbook: stack layout, Sidekiq, CMS coupling, DigitalOcean rollback
remetrics Update Workflow - How to deploy code changes to the remetrics Rails app and Strapi CMS

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

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

6.8 KiB Raw Permalink Blame History