111 lines
4.7 KiB
Markdown
111 lines
4.7 KiB
Markdown
# 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.
|