portioner/.agent/instructions.md

AI Agent Maintenance Instructions

When maintaining this repository, you MUST adhere to the following rules based on the REQUIREMENTS.md.

Guidelines for Adding/Modifying Services

1. Volume Mapping:

   • ALWAYS map system data to /volume1/docker/<service>.
   • ALWAYS map large user data to /volume1/media/<type>.
   • Use environment variables (e.g., ${DOCKER_BASE:-/volume1/docker}) if possible for flexibility.

2. Setup Scripts:

   • If a setup script does not exist, CREATE one named create_<service>_folders.sh in the service directory.
   • Use the following template for scripts:

     #!/bin/bash
     BASE="/volume1/docker/service_name"
     MEDIA="/volume1/media/service_data"
     mkdir -p "$BASE/config" "$BASE/data" "$MEDIA"
     chown -R PUID:PGID "$BASE" "$MEDIA"
     chmod -R 750 "$BASE" "$MEDIA"
     

   • Ensure the script is idempotent (safe to run multiple times).

3. Setup Documentation (SETUP.md):

   • Create a SETUP.md file in the service directory based on SERVICE_SETUP_TEMPLATE.md.
   • Explicitly highlight MANUAL steps like Synology user creation and PUID/PGID lookup.
   • Describe what the setup script does and what environment variables are needed.

4. Docker Compose (Portainer Stacks):

   • Name the file docker-compose.portainer.yml.
   • Group dependent containers (DB, Cache) in the same file.
   • Use user: "${PUID}:${PGID}" unless root is required.
   • Prefer env_file: stack.env for environment variable management.

5. Code Quality:

   • Check for typos in filenames and configurations.
   • Ensure consistent naming conventions across all service directories.