dotfiles_arch/ansible/AGENTS.md

Agent Guidelines for Ansible Infrastructure Repository

This repository contains Docker Compose infrastructure configurations for deploying self-hosted productivity services. This document provides guidelines for AI coding agents working in this repository.

Project Overview

Type: Docker Compose Infrastructure Project
Primary Technology: Docker, Docker Compose
Purpose: Deployment configurations for self-hosted productivity stack including Nextcloud, OnlyOffice, Excalidraw, and Obsidian

Repository Structure

/home/liph/programming/ansible/
└── nextcloud/
    ├── docker-compose.yml    # Main orchestration file (5 services)
    └── .env                  # Environment variables

Commands

Docker Compose Operations

# Navigate to service directory
cd nextcloud/

# Start all services
docker compose up -d

# Start specific service
docker compose up -d <service-name>

# Stop all services
docker compose down

# Stop and remove volumes (DESTRUCTIVE)
docker compose down -v

# View logs for all services
docker compose logs -f

# View logs for specific service
docker compose logs -f <service-name>

# Restart a service
docker compose restart <service-name>

# Rebuild and restart service
docker compose up -d --build <service-name>

# Validate docker-compose.yml syntax
docker compose config

# List running services
docker compose ps

Service Names

• excalidraw - Drawing/whiteboard tool (port 3009)
• next-db - PostgreSQL 18 database
• next - Nextcloud main application (port 8808)
• onlyoffice - Document server (port 8000)
• obsidian - Note-taking app (ports 3004-3005)

Testing

No automated tests exist. Manual testing workflow:

1. Validate syntax: docker compose config
2. Start services: docker compose up -d
3. Check health: docker compose ps
4. Review logs: docker compose logs
5. Test endpoints: curl localhost:8808 (Nextcloud), etc.

Code Style Guidelines

YAML Formatting (docker-compose.yml)

Indentation:

• Use 2 spaces for indentation (NO tabs)
• Maintain consistent indentation levels

Structure:

services:
  service-name:
    image: docker.io/image:tag
    container_name: container-name
    depends_on:
      - dependency
    ports:
      - "host:container"
    environment:
      - KEY=value
      - KEY=${ENV_VAR}
    volumes:
      - volume_name:/container/path
      - ./host/path:/container/path
    restart: unless-stopped
    networks:
      - network_name

Naming Conventions:

• Container names: Use kebab-case (e.g., next-db, next-redis)
• Service names: Use snake_case or kebab-case consistently
• Volume names: Use snake_case (e.g., nextcloud_data, pg_data)
• Network names: Use snake_case with project prefix (e.g., nextcloud_network)

Environment Variables:

• Reference .env variables using ${VAR_NAME} syntax
• Never hardcode sensitive data (passwords, secrets) in docker-compose.yml
• Use explicit environment variable declarations with - prefix

Image Specifications:

• Always use fully qualified image names: docker.io/image:tag
• Pin specific versions for production (avoid :latest in production)
• Current exception: development environment uses :latest tags

Volumes:

• Named volumes for persistent data (defined in volumes section)
• Bind mounts for configuration files using ./relative/path
• Always specify volume mount destination path
• CRITICAL: Never leave empty volume definitions (e.g., - :/path)

Comments:

• Use # for comments
• Add comments above service definitions to describe purpose
• Comment out optional services with # prefix on each line

Environment Files (.env)

Format:

# Database Configuration
DB_PASSWORD=secure_password_here
DB_USERNAME=nextcloud
DB_DATABASE_NAME=nextcloud
DB_HOST=next-db

# User/Group IDs
PUID=33
PGID=1000

Rules:

• One variable per line: KEY=value
• No spaces around =
• No quotes needed for values
• Group related variables with comment headers
• Never commit sensitive values (use placeholders or .env.example)
• All variables must have values (no empty assignments)

Security Guidelines

1. Secrets Management:

   • Never hardcode passwords in docker-compose.yml
   • Use .env file for credentials (ensure .env is in .gitignore)
   • Consider Docker secrets for sensitive production data
   • Rotate default passwords immediately

2. Current Security Issues to Fix:

   • Line 53 in docker-compose.yml: Remove hardcoded admin password
   • .env file: All database credentials are empty
   • Consider enabling JWT for OnlyOffice (currently disabled)

3. Network Security:

   • Use isolated Docker networks for service communication
   • Only expose necessary ports to host
   • Consider reverse proxy (nginx/traefik) for HTTPS termination

Error Handling

Validation Steps Before Committing:

1. Run docker compose config to validate YAML syntax
2. Ensure all volume mount paths are complete
3. Verify all environment variables are defined in .env
4. Check for hardcoded secrets
5. Confirm port conflicts with docker compose ps

Common Issues:

• Empty volume definitions: Always specify source and destination
• Missing environment variables: Define all referenced vars in .env
• Port conflicts: Use docker ps to check existing port bindings
• Network errors: Ensure services on same network can communicate

Configuration Management

Volume Mapping Patterns:

# Named volume (recommended for data)
volumes:
  - nextcloud_data:/var/www/html

# Bind mount with SELinux label (for config)
volumes:
  - ./config:/var/www/html/config:Z

# Bind mount with shared label
volumes:
  - ./vault:/vault:z

Restart Policies:

• Use restart: unless-stopped for production services
• Avoid restart: always (harder to stop deliberately)
• Use restart: on-failure for development/debugging

Database Configuration

PostgreSQL Environment Variables:

• POSTGRES_DB - Database name
• POSTGRES_USER - Database user
• POSTGRES_PASSWORD - Database password

Nextcloud Database Connection:

• POSTGRES_HOST - Hostname (service name: next-db)
• Must match database service configuration

Best Practices

1. Service Dependencies:

   • Use depends_on to define startup order
   • Note: depends_on doesn't wait for "ready" state

2. Resource Limits:

   • Consider adding memory/CPU limits for production
   • Current config uses mem_swappiness: -1 for Nextcloud

3. Timezone Configuration:

   • Set TZ environment variable for correct timestamps
   • Current: TZ=Europe/Zurich (Excalidraw), TZ=Etc/UTC (Obsidian)

4. Data Persistence:

   • Always use named volumes for important data
   • Define volumes in top-level volumes: section
   • Backup volume data regularly

5. Making Changes:

   • Test changes in development before production
   • Use docker compose config to validate
   • Review diff carefully before applying
   • Document breaking changes

Development Workflow

1. Make changes to docker-compose.yml or .env
2. Validate: docker compose config
3. Apply changes: docker compose up -d
4. Verify: docker compose ps && docker compose logs
5. Test affected services manually
6. Document changes in commit message

Critical Fixes Needed

• Complete empty volume mount paths (lines 21, 55-57, 74, 89-90)
• Remove hardcoded admin password (line 53)
• Populate database credentials in .env file
• Add .gitignore to exclude .env from version control
• Consider adding docker-compose.override.yml for local development