qbitcheck/DEPLOYMENT.md

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:

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

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

# 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

# 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