silverbullet-notes/Onboarding_a_New_Service.md

Onboarding a New Service

This document provides a step-by-step checklist for adding a new service to the infrastructure. Following this guide ensures that new services are configured consistently, securely, and are integrated with the existing automation and backup systems.

1. Directory Structure

1. Create Service Directory: Create a new directory for the service under /mnt/docker-storage/appdata/.

   mkdir /mnt/docker-storage/appdata/[service-name]
   cd /mnt/docker-storage/appdata/[service-name]
   

2. Create docker-compose.yml: Create a docker-compose.yml file for the service.
3. Create Data Directories: Create any necessary subdirectories for configuration, data, etc.

2. Docker Compose Configuration

Your docker-compose.yml should include the following standard configurations:

• Image: Use a specific version tag if possible (e.g., lscr.io/linuxserver/readarr:develop) instead of latest to avoid unexpected breaking changes.
• Container Name: Set a consistent container name (e.g., container_name: [service-name]).
• Environment Variables:
  • PUID=1000 and PGID=1000
  • TZ=America/New_York
• Volumes:
  • Map the configuration volume to ./config or another subdirectory within the service's appdata folder.
  • Map any shared volumes (e.g., /volume1/Media) as needed, using :ro for read-only access where appropriate.
• Restart Policy: restart: unless-stopped
• Networks:
  • Add the service to the traefik_proxy external network.

  networks:
    traefik_proxy:
      external: true
  

3. Traefik Integration (for web services)

To expose a service via Traefik, add the following labels to your docker-compose.yml:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.[service-name].rule=Host(`[service-name].3ddbrewery.com`)"
  - "traefik.http.routers.[service-name].entrypoints=websecure"
  - "traefik.http.routers.[service-name].tls.certresolver=myresolver"
  - "traefik.http.services.[service-name].loadbalancer.server.port=[port]"

• Replace [service-name] and [port] with the appropriate values.

4. Authelia Integration (for protected services)

To protect a service with Authelia SSO, add the Authelia middleware to the Traefik router:

labels:
  # ... other Traefik labels
  - "traefik.http.routers.[service-name].middleware=authelia-brewery"

• If the service has an API that needs to be exposed without authentication, create a separate router for the API path.

5. Homepage Integration

To add the new service to the Homepage dashboard, add the following labels:

labels:
  # ... other labels
  - "homepage.group=[Group Name]"
  - "homepage.name=[Service Name]"
  - "homepage.href=https://[service-name].3ddbrewery.com"
  - "homepage.icon=[icon-name].png" # or .svg
  - "homepage.description=[Description]"

• Refer to the Homepage documentation for available icons and widget configurations.

6. Backup Integration

ArchiveForge automatically backs up the entire /mnt/docker-storage/appdata directory, so no specific configuration is usually needed for a new service to be included in backups.

However, you should consider the following:

• Databases: If the service uses a database, ArchiveForge's auto_detect_databases feature should handle it. You can verify this by checking the ArchiveForge logs during a backup cycle.
• Sensitive Data: If the service stores data outside of its appdata directory, you may need to add a new source to ArchiveForge's config.yaml.
• Never Stop: If the service is critical and should not be stopped during backups, add its container name to the never_stop list in archiveforge/config/config.yaml.

7. Resource Limits

As recommended in the efficiency review, all new services should have resource limits defined to prevent resource exhaustion.

Add a deploy section with resources and limits to your docker-compose.yml:

deploy:
  resources:
    limits:
      memory: 512M  # Adjust based on the service's needs
      cpus: '0.5'   # Adjust based on the service's needs

8. Final Checks

1. Start the Service: docker-compose up -d
2. Check Logs: docker-compose logs -f
3. Verify Web Access: Check the service's URL.
4. Verify Authelia: Ensure you are prompted for authentication if the service is protected.
5. Verify Homepage: Check that the service appears correctly on the dashboard.
6. Trigger Manual Backup: Consider triggering a manual ArchiveForge backup and check the logs to ensure the new service is backed up correctly.
7. Update Documentation: Add the new service to Infrastructure.md and any other relevant documentation.