sync

DEPLOYMENT.md

@@ -0,0 +1,153 @@
+# Qbitcheck Deployment Guide
+
+## Overview
+
+Qbitcheck is a Python application that monitors qBittorrent connection status and manages remediation when connections fail. This document covers deployment using Docker and Nomad.
+
+## Docker Container
+
+### Building the Container
+
+The container can be built using the provided Dockerfile:
+
+```bash
+docker build -t gitea.service.dc1.fbleagh.duckdns.org/sstent/qbitcheck:latest .
+```
+
+### Container Details
+
+- **Base Image**: Python 3.11-slim
+- **Working Directory**: `/app`
+- **Entrypoint**: `python main.py`
+- **Health Check**: Process check every 30 seconds
+- **Dependencies**: requests, python-consul
+
+### Running Locally
+
+```bash
+docker run -d --name qbitcheck gitea.service.dc1.fbleagh.duckdns.org/sstent/qbitcheck:latest
+```
+
+## Nomad Deployment
+
+### Job Specification
+
+The Nomad job specification is located in [`qbitcheck.nomad`](qbitcheck.nomad:1). Key features:
+
+- **Job Type**: Service
+- **Resources**: 100MHz CPU, 128MB RAM
+- **Network**: Host mode
+- **Restart Policy**: Exponential backoff with 10 attempts
+- **Health Checks**: Process verification
+
+### Deploying to Nomad
+
+```bash
+# Plan the job
+nomad plan qbitcheck.nomad
+
+# Run the job
+nomad run qbitcheck.nomad
+
+# Check job status
+nomad status qbitcheck
+```
+
+### Service Discovery
+
+The job includes Consul service registration with:
+- Service name: `qbitcheck`
+- Health checks for process monitoring
+- URL prefix tag for routing
+
+## GitHub Actions CI/CD
+
+### Automated Build Pipeline
+
+The GitHub workflow (`.github/workflows/container-build.yml`) automatically builds and pushes the container on:
+
+- Push to `main` branch with changes to relevant files
+- Manual workflow dispatch
+
+### Build Process
+
+1. **Multi-architecture**: Builds for both `linux/amd64` and `linux/arm64`
+2. **Registry**: Pushes to `gitea.service.dc1.fbleagh.duckdns.org/sstent/qbitcheck`
+3. **Tags**: `latest` and git commit SHA
+4. **Caching**: Uses GitHub Actions caching for faster builds
+
+### Required Secrets
+
+Ensure these secrets are configured in GitHub:
+
+- `GITEA_TOKEN`: Authentication token for Gitea registry
+- `PACKAGE_TOKEN`: Alternative token (fallback)
+- `GITHUB_TOKEN`: Default GitHub token (fallback)
+
+## Configuration
+
+### Hardcoded Values
+
+All configuration is currently hardcoded in the application:
+
+- **qBittorrent URL**: `http://sp.service.dc1.consul:8080`
+- **Nomad URL**: `http://192.168.4.36:4646`
+- **Consul URL**: `http://consul.service.dc1.consul:8500`
+- **Tracker Name**: `https://t.myanonamouse.net/tracker.php/VPRYYAL-WpTwnr9G9aIN6044YVZ7x8Ao/announce`
+- **Credentials**: admin/adminpass
+
+### Service Dependencies
+
+The application requires access to:
+- qBittorrent API (port 8080)
+- Nomad API (port 4646)
+- VPN Monitoring API (port 8000)
+- Consul (port 8500)
+
+## Monitoring and Logging
+
+### Logs
+
+- Container logs output to stdout/stderr
+- Nomad captures and manages logs
+- Connection status and remediation actions are logged
+
+### Health Checks
+
+- Process health check every 30 seconds
+- Automatic restart on failure
+- Exponential backoff for restart attempts
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Network Connectivity**: Ensure all dependent services are accessible
+2. **Authentication**: Verify qBittorrent credentials if changed
+3. **Resource Limits**: Monitor memory usage if experiencing OOM kills
+
+### Debugging
+
+```bash
+# View container logs
+docker logs qbitcheck
+
+# View Nomad allocation logs
+nomad alloc logs -f <allocation-id>
+
+# Check service health in Consul
+consul catalog services
+```
+
+## Versioning
+
+- Container tags include git commit SHA for traceability
+- `latest` tag points to most recent successful build
+- Rollback by deploying previous SHA-tagged image
+
+## Security Considerations
+
+- Runs with minimal privileges
+- No sensitive data in environment variables (all hardcoded)
+- Network access limited to required services
+- Regular security updates via base image updates