docs: update AGENTS.md for mono-repo and Debian 13 environment
Update agent instructions to reflect new mono-repo structure, Debian 13 host, and KVM/QEMU testing capabilities. Changes: - Update to Debian 13 host with KVM/QEMU virtualization - Add Terraform + libvirt for local VM testing - Update production deployment to use OVH provider - Document mono-repo directory structure - Add Grav CMS integration - Add Ansible for post-VM configuration - Document provider abstraction (local libvirt → production OVH) - Update container naming convention (YDN-Dev-*) - Document all services (API, Worker, Middleware, Dolibarr, Grav) - Add comprehensive infrastructure workflow documentation This ensures AI agents have complete understanding of the updated mono-repo architecture and development workflow. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
217
AGENTS.md
217
AGENTS.md
@@ -1,10 +1,207 @@
|
|||||||
Perfrom all work in the output/ subdirectory. DO NOT create ANYTHING at the top level directory.
|
# YDN Agent Instructions
|
||||||
Ensure all work is fully tested, done in docker container (prefixed with YDN-Dev-)
|
|
||||||
Follow 12 factor principles
|
## Project Overview
|
||||||
Standup a full local dev stack including Dollibarr
|
YDN is a mono-repo SaaS platform providing sovereign hosting stacks for $250/month per domain.
|
||||||
Use docker containers for ALL work. DO NOT pollute the host
|
Customer provides credit card, domain name, email address → receives OVH domain, OVH VPS, Cloudron, DNS integration.
|
||||||
Write the application in the go language
|
|
||||||
Use docker containers for the application.
|
## Development Environment
|
||||||
They should be able to be pushed to a private registyr and deplopyed. Create the docker-compose.yml.
|
- **Host**: Debian 13 with KVM/QEMU virtualization
|
||||||
YOu will be doing development/testing/deployment end to end
|
- **Testing**: Terraform + libvirt provider for local VM provisioning
|
||||||
The deployment environment is a Ubuntu 24.04 host with SSH installed. YOu'll need to ssh in as root and deploy the containers, setup web frontend etc etc.
|
- **Production**: Swap to real providers (OVH initially)
|
||||||
|
- **Approach**: 12-factor principles, containerized services
|
||||||
|
|
||||||
|
## Mono-Repo Structure
|
||||||
|
```
|
||||||
|
/home/charles/Projects/YDN/
|
||||||
|
├── services/ # Go microservices
|
||||||
|
│ ├── api/ # Main HTTP API server
|
||||||
|
│ ├── worker/ # Background job processor
|
||||||
|
│ └── middleware/ # VPS provisioning middleware
|
||||||
|
├── web/ # Grav CMS (public website)
|
||||||
|
├── backend/ # Dolibarr (ERP/CRM)
|
||||||
|
├── infrastructure/ # IaC and automation
|
||||||
|
│ ├── terraform/ # VM provisioning (local + production)
|
||||||
|
│ │ ├── modules/ # Reusable Terraform modules
|
||||||
|
│ │ ├── environments/ # Local, staging, production configs
|
||||||
|
│ │ └── providers/ # libvirt (local), ovh (production)
|
||||||
|
│ └── ansible/ # Post-VM creation configuration
|
||||||
|
│ ├── playbooks/ # Ansible playbooks
|
||||||
|
│ ├── roles/ # Ansible roles
|
||||||
|
│ └── inventory/ # Dynamic inventory scripts
|
||||||
|
├── docker/ # Docker configurations
|
||||||
|
│ ├── docker-compose.yml # Development stack
|
||||||
|
│ ├── docker-compose.prod.yml # Production stack
|
||||||
|
│ └── Dockerfile.* # Service Dockerfiles
|
||||||
|
├── config/ # Configuration files
|
||||||
|
│ ├── env/ # Environment-specific configs
|
||||||
|
│ └── templates/ # Config templates
|
||||||
|
├── docs/ # Documentation
|
||||||
|
│ ├── api/ # API documentation
|
||||||
|
│ ├── architecture/ # Architecture docs
|
||||||
|
│ └── operations/ # Operational guides
|
||||||
|
├── scripts/ # Utility scripts
|
||||||
|
│ ├── deploy.sh # Deployment automation
|
||||||
|
│ ├── test.sh # Test runner
|
||||||
|
│ └── backup.sh # Backup scripts
|
||||||
|
├── tests/ # Test suites
|
||||||
|
│ ├── unit/ # Unit tests
|
||||||
|
│ ├── integration/ # Integration tests
|
||||||
|
│ └── e2e/ # End-to-end tests
|
||||||
|
├── go.work # Go workspace file (for mono-repo)
|
||||||
|
├── Makefile # Common commands
|
||||||
|
├── README.md # Project overview
|
||||||
|
├── PRD.md # Product requirements
|
||||||
|
└── AGENTS.md # This file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
### Core Services (Go)
|
||||||
|
- **services/api**: Main HTTP server, business logic, orchestration
|
||||||
|
- **services/worker**: Background job processing, async tasks
|
||||||
|
- **services/middleware**: VPS provisioning abstraction layer
|
||||||
|
|
||||||
|
### CMS (Grav)
|
||||||
|
- **web/grav**: Flat-file CMS for public website, documentation
|
||||||
|
- Docker containerized
|
||||||
|
- Integrates with API for dynamic content
|
||||||
|
|
||||||
|
### ERP/CRM (Dolibarr)
|
||||||
|
- **backend/dolibarr**: Complete business management
|
||||||
|
- Prospects, customers, contracts, invoices, support tickets
|
||||||
|
- Docker containerized with MySQL
|
||||||
|
|
||||||
|
### Infrastructure
|
||||||
|
- **terraform**: Multi-provider abstraction
|
||||||
|
- Local testing: `dmacvicar/libvirt` provider (KVM/QEMU on Debian 13)
|
||||||
|
- Production: `ovh/ovh` provider
|
||||||
|
- Modules: VM provisioning, networking, security
|
||||||
|
- **ansible**: Post-VM configuration
|
||||||
|
- OS hardening
|
||||||
|
- Docker installation
|
||||||
|
- Cloudron deployment
|
||||||
|
- DNS configuration
|
||||||
|
- Security setup
|
||||||
|
|
||||||
|
### Deployment Targets
|
||||||
|
- **Development**: Debian 13 host with KVM/QEMU (Terraform + libvirt)
|
||||||
|
- **Production**: OVH infrastructure (Terraform + OVH provider)
|
||||||
|
- Swap providers via Terraform backend configuration
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
### 1. Local Development
|
||||||
|
```bash
|
||||||
|
# Start development stack
|
||||||
|
docker-compose -f docker/docker-compose.yml up -d
|
||||||
|
|
||||||
|
# Run Go services in containers
|
||||||
|
# All services prefixed with YDN-Dev-
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. VM Testing (Local)
|
||||||
|
```bash
|
||||||
|
# Provision test VM via Terraform
|
||||||
|
cd infrastructure/terraform/environments/local
|
||||||
|
terraform apply
|
||||||
|
|
||||||
|
# Configure VM via Ansible
|
||||||
|
cd ../../../ansible
|
||||||
|
ansible-playbook -i inventory/local.yml playbooks/provision.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Production Deployment
|
||||||
|
```bash
|
||||||
|
# Switch to production provider
|
||||||
|
cd infrastructure/terraform/environments/production
|
||||||
|
terraform apply
|
||||||
|
|
||||||
|
# Ansible for post-creation config
|
||||||
|
cd ../../../ansible
|
||||||
|
ansible-playbook -i inventory/production.yml playbooks/provision.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
### Mono-Repo Management
|
||||||
|
- All services in single repository
|
||||||
|
- Go workspace for module management
|
||||||
|
- Shared packages in `pkg/` directory
|
||||||
|
- Coordinated releases via tags
|
||||||
|
|
||||||
|
### Provider Abstraction
|
||||||
|
- Terraform modules are provider-agnostic
|
||||||
|
- Swap local libvirt for production providers
|
||||||
|
- Ansible playbooks work across all environments
|
||||||
|
- Same configuration, different backend
|
||||||
|
|
||||||
|
### Containerization
|
||||||
|
- EVERYTHING in Docker containers
|
||||||
|
- Container names: `YDN-Dev-*` (dev), `YDN-Prod-*` (prod)
|
||||||
|
- Private registry for deployment
|
||||||
|
- No host pollution
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- Integration tests use local VMs
|
||||||
|
- E2E tests with full stack
|
||||||
|
- Mock external APIs (Stripe, OVH) where needed
|
||||||
|
- Accessibility testing (WCAG 2.1 AA)
|
||||||
|
|
||||||
|
### Dolibarr Integration (CRITICAL)
|
||||||
|
- ALL business operations go through Dolibarr
|
||||||
|
- Prospects created on email verification
|
||||||
|
- Customers converted on payment
|
||||||
|
- Contracts, invoices, support tickets
|
||||||
|
- API integration mandatory
|
||||||
|
|
||||||
|
### VPS Provisioning
|
||||||
|
1. Terraform provisions VM (local libvirt or production OVH)
|
||||||
|
2. Ansible configures post-creation (OS, Docker, Cloudron)
|
||||||
|
3. Middleware service orchestrates entire flow
|
||||||
|
4. Status tracked via API
|
||||||
|
|
||||||
|
## Deployment Process
|
||||||
|
|
||||||
|
### Development
|
||||||
|
1. Code changes in appropriate service directory
|
||||||
|
2. Test locally with `docker-compose`
|
||||||
|
3. Deploy to staging environment
|
||||||
|
4. Integration tests with Terraform + Ansible
|
||||||
|
|
||||||
|
### Production
|
||||||
|
1. Update terraform environment configs
|
||||||
|
2. `terraform apply` for VM provisioning
|
||||||
|
3. `ansible-playbook` for configuration
|
||||||
|
4. Deploy Go services via `scripts/deploy.sh`
|
||||||
|
5. Monitor via Dolibarr + API metrics
|
||||||
|
|
||||||
|
## CI/CD Pipeline (Future)
|
||||||
|
- Automated testing on push
|
||||||
|
- Terraform validation
|
||||||
|
- Ansible syntax checking
|
||||||
|
- Go tests + linting
|
||||||
|
- Security scanning
|
||||||
|
- Deploy to staging
|
||||||
|
- Manual approval for production
|
||||||
|
|
||||||
|
## Security
|
||||||
|
- All secrets in environment variables or secret managers
|
||||||
|
- SSH keys managed via Ansible Vault
|
||||||
|
- TLS/SSL for all services
|
||||||
|
- Firewall rules via Terraform + Ansible
|
||||||
|
- Regular backups (automated)
|
||||||
|
|
||||||
|
## Accessibility
|
||||||
|
- WCAG 2.1 AA compliance for all web interfaces
|
||||||
|
- Grav CMS: accessible templates
|
||||||
|
- API: proper error messages
|
||||||
|
- Documentation: screen reader compatible
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
- NEVER create files outside designated mono-repo structure
|
||||||
|
- ALWAYS use Docker containers for services
|
||||||
|
- PROVIDER SWAP is key capability (test locally, deploy to prod)
|
||||||
|
- DOLIBARR integration is non-negotiable
|
||||||
|
- ANSIBLE handles all post-VM configuration
|
||||||
|
- TERRAFORM handles VM provisioning
|
||||||
|
- MIDDLEWARE orchestrates VPS lifecycle
|
||||||
|
|||||||
Reference in New Issue
Block a user