Installation

This repo supports three install modes — dev, production (bare metal), and Docker:

[toc]

Requirements

  • Python 3.10+
  • uv
  • Dependencies are defined in pyproject.toml

1) Quick install

1.1 Clone the repo 

git clone git@github.com:ikidnapmyself/server-monitoring.git
cd server-monitoring

1.2 Run the installer 

./bin/install.sh

If you get “permission denied”, run:

chmod +x ./bin/*.sh

What the installer does (in order)

./bin/install.sh performs these steps:

  • Verifies Python is 3.10+
  • Installs uv if missing
  • Ensures you have a .env (creates it from .env.sample if present)
  • Prompts you for dev, production, or docker mode and appends missing .env keys
    • It does not overwrite existing values
  • Installs dependencies with uv sync
    • dev installs include dev extras
    • prod installs are runtime-only
  • Runs Django migrations
  • Runs python manage.py check
  • Optionally runs health checks now
  • Optionally sets up cron via ./bin/install.sh cron
  • Optionally sets up shell aliases via ./bin/install.sh aliases

See the installer implementation in bin/install.sh.

2) Cron setup (optional)

If you didn’t enable cron during install, you can run it later:

./bin/install.sh cron

What it does

  • Detects the project directory automatically
  • Lets you choose a schedule (every 5 min / 15 min / hourly / etc. or custom)
  • Writes a crontab entry that runs:
uv run python manage.py run_pipeline --checks-only --json
  • Logs output to cron.log in the project root

See the cron script in bin/install.sh cron.

Useful commands 

crontab -l
tail -f ./cron.log

3) Shell aliases (optional)

Shell aliases let you run sm-check-health instead of uv run python manage.py check_health.

If you didn’t set up aliases during install, run:

./bin/install.sh aliases

It will prompt for a prefix (default: sm), generate aliases, and add a source line to your shell profile.

Key aliases

Alias What it does
sm-check-health Run health checks (CPU, memory, disk, network, process)
sm-run-pipeline Execute pipelines (definition-based or sample)
sm-setup-instance Interactive wizard to create pipelines and notification channels
sm-check-and-alert Run checks through the pipeline (run_pipeline --checks-only)
sm-get-recommendations Get AI-powered system recommendations
sm-cli Interactive CLI menu

All aliases pass flags through: sm-check-health --json = uv run python manage.py check_health --json.

See bin/README.md for the full alias table and script details.

Custom prefix 

./bin/install.sh aliases --prefix maint
# Creates: maint-check-health, maint-run-pipeline, etc.

Remove aliases 

./bin/install.sh aliases --remove

Profiles

The installer supports saving and loading configuration profiles for consistent deployments across machines.

Saving a Profile

After running the installer, save the configuration:

./bin/install.sh --save-profile prod-web

This creates .install-profile-prod-web containing all non-sensitive configuration values.

Loading a Profile

On a new machine, load a saved profile to pre-fill all prompts:

./bin/install.sh --profile prod-web

Values from the profile appear as defaults — press Enter to accept or type a new value to override.

Non-Interactive Mode

For automated deployments, combine --profile with --yes to accept all defaults:

./bin/install.sh --profile prod-web --yes

Only secrets (DJANGO_SECRET_KEY, WEBHOOK_SECRET_CLUSTER) will still be prompted since they are never stored in profiles.

After installation, use the interactive CLI for a guided experience:

./bin/cli.sh

The CLI provides menus for all management commands with their available options.

Direct shortcuts:

./bin/cli.sh health     # Health monitoring
./bin/cli.sh intel      # Intelligence recommendations
./bin/cli.sh pipeline   # Pipeline orchestration
./bin/cli.sh notify     # Notifications

5) System health check

Verify your installation is working correctly:

./bin/check_system.sh

This auto-detects your deployment mode (dev/prod/docker/systemd) and runs the relevant checks — Python version, uv, .env, .venv, Django, migrations, pre-commit hooks, Docker containers, or systemd services.

./bin/check_system.sh --json    # JSON output (for CI/monitoring)

6) Manual installation (no scripts)

Use this if you want full control or you’re running in CI.

5.1 Clone 

git clone git@github.com:ikidnapmyself/server-monitoring.git
cd server-monitoring

5.2 Create and activate a virtualenv 

python3 -m venv .venv
. .venv/bin/activate

5.3 Install uv (via pip) 

python -m pip install --upgrade pip
pip install uv

5.4 Create your .env 

cp .env.sample .env

Set at least a secret key (required for real deployments):

# example
echo 'DJANGO_SECRET_KEY=change-me' >> .env

5.5 Install dependencies

Production-style (no dev tools):

uv sync --frozen --no-dev

Dev install (includes dev tools/extras):

uv sync --all-extras --dev

5.6 Migrate 

uv run --frozen python manage.py migrate --noinput

5.7 Django system check 

uv run python manage.py check

5.8 Run the server 

uv run python manage.py runserver

7) Common commands

With aliases (after running ./bin/install.sh aliases):

sm-check-health                  # Run health checks
sm-check-health --list           # List available checkers
sm-check-and-alert --json        # Run checks through pipeline (cron-friendly)
sm-get-recommendations --all     # Get system recommendations
sm-run-pipeline --sample         # Run pipeline with sample alert

Without aliases:

uv run python manage.py check_health
uv run python manage.py check_health --list
uv run python manage.py run_pipeline --checks-only --json
uv run python manage.py get_recommendations --all
uv run python manage.py run_pipeline --sample

8) Pipeline workflow with aliases

Definition-based pipelines let you compose custom monitoring workflows. Here’s the typical workflow using shell aliases:

Step 1: Create a pipeline and notification channels 

sm-setup-instance

The interactive wizard walks you through:

  • Choosing which health checkers to enable
  • Configuring notification channels (Slack, email, PagerDuty, generic webhook)
  • Creating a PipelineDefinition in the database (e.g., local-monitor)

Step 2: Validate with dry-run 

sm-run-pipeline --definition local-monitor --dry-run

This shows the node chain and config without executing anything.

Step 3: Run the pipeline 

sm-run-pipeline --definition local-monitor

This runs real health checks and sends real notifications through the channels you configured.

More examples 

# Run from a JSON file instead of a DB definition
sm-run-pipeline --config apps/orchestration/management/commands/pipelines/local-monitor.json

# Run with a sample alert payload (for testing ingest-based pipelines)
sm-run-pipeline --definition local-monitor --sample

# Monitor pipeline run history
sm-monitor-pipeline

# Test notification delivery without running a pipeline
sm-test-notify --driver slack

Without aliases

The same workflow without aliases:

uv run python manage.py setup_instance
uv run python manage.py run_pipeline --definition local-monitor --dry-run
uv run python manage.py run_pipeline --definition local-monitor

For full pipeline documentation including node types, config options, and troubleshooting, see apps/orchestration/README.md.

9) Production deployment

For production deployment with Celery workers, Redis, and Nginx, see the Deployment Guide. It covers:

  • Docker Compose — full stack with Django, Celery, and Redis (recommended for quick deploys)
  • Bare metal / VPS — systemd units for gunicorn and Celery worker
  • Nginx reverse proxy — static files, proxy headers, SSL termination
  • Webhook ingestion — async pipeline processing with automatic fallback
This site uses Just the Docs, a documentation theme for Jekyll.