server-maintanence
A small, modular Django project for basic server maintenance / monitoring workflows.
This top-level README is the entry point and documentation hub. App-specific docs live alongside the apps.
Documentation map
Requirements
- Python 3.10+
- Package manager: uv (recommended, repo includes
uv.lock)
Dependencies (from pyproject.toml): Django + psutil.
Install
See Installation document docs/Installation.md.
Usage modes
This project supports two modes — see Architecture for full details:
- Pipeline controller: Ingest alerts and route through intelligence + notify stages.
- Individual server monitor: Run health checks locally and optionally generate alerts.
Quick examples:
# Pipeline mode (sync, with sample alert)
uv run python manage.py run_pipeline --sample
# Standalone health checks
uv run python manage.py check_health
# Run checks and generate alerts
uv run python manage.py run_pipeline --checks-only
Environment configuration (.env / dotenv)
This project supports dotenv files via python-dotenv.
- Create a local
.env by copying .env.sample.
- Optionally use
.env.dev for dev-only defaults by setting DJANGO_ENV=dev.
- Values already present in your shell environment take precedence (dotenv never overrides existing vars).
Common variables:
DJANGO_SECRET_KEY (required in production; local dev can fall back to an insecure default)DJANGO_DEBUG (1/0)DJANGO_ALLOWED_HOSTS (comma-separated)INBOX_DEPTH_WARN (drain backlog warning threshold; the pipeline is broker-free)
Development
This repo uses uv for dependency management and a small, consistent dev-tooling stack configured in pyproject.toml:
- Black for formatting
- Ruff for linting + import sorting
- pytest + pytest-django for tests
- mypy + django-stubs (optional) for type-checking
Common commands
# Install runtime + dev tools
uv sync --extra dev
# Set up pre-commit hooks
uv run pre-commit install
# Run pre-commit manually on all files
uv run pre-commit run --all-files
# Format
uv run black .
# Lint (and auto-fix imports where possible)
uv run ruff check . --fix
# Tests
uv run pytest
# Test coverage (100% branch coverage required)
uv run coverage run -m pytest && uv run coverage report
# Optional: type-check
uv run mypy .
Quickstart
- Create a local env file:
cp .env.sample .env
- Apply migrations:
uv run python manage.py migrate
- Run the interactive CLI (recommended for new users):
./bin/cli.sh
The CLI guides you through all available commands with their options.
- (Optional) Set up shell aliases for quick command access:
./bin/install.sh aliases
After setup, use aliases like sm-check-health, sm-run-check, etc. See bin/README.md for the full alias list.
Alternatively, run commands directly:
# Run the health check suite
uv run python manage.py check_health
# List available checkers
uv run python manage.py check_health --list
(Optional) Run the Django server:
uv run python manage.py runserver
Project layout
config/ — Django project settings/urls/asgi/wsgiapps/ — Django apps
apps/checkers/ — health checks + management commandsapps/alerts/ — alert ingestion (scaffold)apps/notify/ — notification drivers (scaffold)apps/intelligence/ — intelligence/recommendations systemapps/orchestration/ — pipeline orchestration (alerts → checkers → intelligence → notify)
bin/ — shell scripts (installer, cron setup, interactive CLI)
Contributing / extending
- Start by reading the app-level README for the area you’re changing.
- If you’re using AI agents in this repo,
AGENTS.md describes the available agent roles and project rules.
License
MIT License (c) 2026 Burak.
See LICENSE.
