# 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/`.
    ```bash
    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.
    ```yaml
    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`:

```yaml
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:

```yaml
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:

```yaml
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`:

```yaml
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.