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 (Intelligent Dry-run by default):

     #!/bin/bash
     DRY_RUN=true
     if [[ "$1" == "--run" || "$1" == "-r" ]]; then DRY_RUN=false; fi
     
     if [ "$DRY_RUN" = "true" ]; then
         echo "--- DRY RUN MODE ---"
         echo "To apply changes, run: sudo bash $0 --run"
         echo "--------------------"
     fi
     
     run_mkdir() {
         local path=$1
         if [ -d "$path" ]; then
             echo "[OK] Folder exists, no changes will be made: $path"
         else
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CREATE] Folder: $path"; else mkdir -p "$path"; fi
         fi
     }
     
     run_chown_recursive() {
         local owner=$1; local path=$2
         local uid=${owner%%:*}; local gid=${owner#*:}
     
         if [ ! -d "$path" ]; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Owner to $owner upon creation: $path"; else chown -R "$owner" "$path"; fi
             return
         fi
     
         if find "$path" \( ! -uid "$uid" -o ! -gid "$gid" \) | grep -q .; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Owner to $owner (recursive): $path"; else chown -R "$owner" "$path"; fi
         else
             echo "[OK] Owner is $owner, no changes will be made: $path"
         fi
     }
     
     run_chmod_recursive() {
         local mode=$1; local path=$2
         if [ ! -d "$path" ]; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL SET] Permissions to $mode upon creation: $path"; else chmod -R "$mode" "$path"; fi
             return
         fi
         if find "$path" ! -perm -"$mode" | grep -q .; then
             if [ "$DRY_RUN" = "true" ]; then echo "[WILL CHANGE] Permissions to $mode (recursive): $path"; else chmod -R "$mode" "$path"; fi
         else
             echo "[OK] Permissions are $mode, no changes will be made: $path"
         fi
     }
     

   • 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.