feat(ansible): ship ansible in image + allow system-triggered runs (task 545)

Foundation for the Ansible automation milestone (#37) — makes the existing
manual playbook runner actually executable and the schema automation-ready.

- pyproject: [ansible] extra (full ansible package, batteries-included, pinned)
- Dockerfile: pip install .[ansible]; add openssh-client for remote runs
- models/ansible.py + migration 0012: AnsibleRun.triggered_by now nullable so
  automated (alert/schedule) runs need no human actor
- ansible/routes.py + run_detail.html: show 'Triggered by' (username or 'system')
- CI: integration lane installs .[dev,ansible]; new tests/integration/
  test_ansible_foundation.py runs a real connection:local playbook end-to-end,
  asserts success+output, and round-trips a NULL-triggered run

No extra-vars/limit/credentials/scheduling here — those are their own #37 tasks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.dockerignore

@@ -26,8 +26,9 @@ config.yaml
 # Runtime data (mounted at runtime via volume)
 playbook_cache/
 
-# Plugins (mounted at runtime via volume)
-plugins/
+# NOTE: first-party plugins under plugins/ now ship IN the image
+# (Dockerfile `COPY plugins/`), so plugins/ must NOT be ignored here.
+# Third-party plugins are mounted at runtime into /data/plugins instead.
 
 # Deployment files not needed in image
 docker-compose.yml

.forgejo/workflows/ci.yml

@@ -85,8 +85,8 @@ jobs:
             sleep 2
           done
           if command -v uv >/dev/null 2>&1; then
-            uv pip install --system -e '.[dev]'
+            uv pip install --system -e '.[dev,ansible]'
           else
-            pip install -e '.[dev]'
+            pip install -e '.[dev,ansible]'
           fi
           pytest tests/integration -v -m integration --durations=10

Dockerfile

@@ -5,6 +5,8 @@ RUN DEBIAN_FRONTEND=noninteractive apt-get update \
         iputils-ping \
         # gosu — minimal privilege-drop tool used by entrypoint.sh
         gosu \
+        # openssh-client — ansible-playbook reaches remote hosts over ssh
+        openssh-client \
     && rm -rf /var/lib/apt/lists/*
 
 # Upgrade pip to suppress the version notice
@@ -14,7 +16,8 @@ WORKDIR /app
 
 COPY pyproject.toml .
 COPY steward/ steward/
-RUN pip install --no-cache-dir .
+# .[ansible] pulls the full Ansible package so the playbook runner works in-image.
+RUN pip install --no-cache-dir '.[ansible]'
 
 COPY alembic.ini .
 # First-party plugins ship inside the image (bundled root at /app/plugins).

docker-compose.yml

@@ -3,17 +3,26 @@ services:
     build: .
     container_name: steward
     image: steward:latest
+    # Dev: --debug turns on Quart's auto-reloader so edits to the mounted source
+    # below take effect without a rebuild.
+    command: ["steward", "--host", "0.0.0.0", "--port", "5000", "--debug"]
     ports:
       - "5000:5000"
     volumes:
-      # First-party plugins are baked into the image at /app/plugins.
-      # Third-party plugins persist in the external root /data/plugins
-      # (inside app_data); STEWARD_PLUGIN_DIR defaults there, no extra mount needed.
       - app_data:/data
-      - /mnt/Data/traefik/log:/var/log/traefik:ro
-      - /var/run/docker.sock:/var/run/docker.sock:ro
+      # Live-edit core + first-party plugins without rebuilding. PYTHONPATH=/app
+      # (below) makes this mounted source win over the image-installed package.
+      - ./steward:/app/steward
+      - ./plugins:/app/plugins
+      # Optional host mounts — enable the matching plugin in Settings first, then
+      # uncomment (the traefik path must exist on this host):
+      #   - /mnt/Data/traefik/log:/var/log/traefik:ro     # traefik plugin
+      #   - /var/run/docker.sock:/var/run/docker.sock:ro  # docker plugin
     environment:
       - STEWARD_DATABASE_URL=postgresql+asyncpg://steward:steward@db/steward
+      # Dev-only fixed key so sessions survive restarts. Replace in production.
+      - STEWARD_SECRET_KEY=dev-secret-key-change-me
+      - PYTHONPATH=/app
     depends_on:
       db:
         condition: service_healthy
@@ -25,6 +34,9 @@ services:
       POSTGRES_USER: steward
       POSTGRES_PASSWORD: steward
       POSTGRES_DB: steward
+    ports:
+      # Exposed for dev convenience (psql from the host). Drop for prod.
+      - "5432:5432"
     volumes:
       - pgdata:/var/lib/postgresql/data
     healthcheck:

pyproject.toml

@@ -26,6 +26,11 @@ ldap = [
 snmp = [
     "pysnmp-lextudio>=6.2",
 ]
+# Batteries-included Ansible (bundles the common community collections) for the
+# playbook runner. Installed into the image via Dockerfile `pip install .[ansible]`.
+ansible = [
+    "ansible>=10,<13",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",

steward/ansible/routes.py

@@ -13,7 +13,7 @@ from sqlalchemy import select
 from steward.ansible import executor, sources as src_module
 from steward.auth.middleware import require_role
 from steward.models.ansible import AnsibleRun, AnsibleRunStatus
-from steward.models.users import UserRole
+from steward.models.users import User, UserRole
 
 ansible_bp = Blueprint("ansible", __name__, url_prefix="/ansible")
 
@@ -165,4 +165,11 @@ async def run_detail(run_id: str):
         run = result.scalar_one_or_none()
         if run is None:
             return "Not found", 404
-    return await render_template("ansible/run_detail.html", run=run)
+        # NULL triggered_by = an automated (system) run; otherwise resolve the user.
+        triggered_label = "system"
+        if run.triggered_by:
+            res = await db.execute(
+                select(User.username).where(User.id == run.triggered_by))
+            triggered_label = res.scalar_one_or_none() or "(deleted user)"
+    return await render_template(
+        "ansible/run_detail.html", run=run, triggered_label=triggered_label)

steward/migrations/versions/0012_ansible_run_triggered_by_nullable.py

@@ -0,0 +1,31 @@
+"""Make ansible_runs.triggered_by nullable (automated runs have no user)
+
+Revision ID: 0012_ansible_run_triggered_by_nullable
+Revises: 0011_audit_log
+Create Date: 2026-06-02
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "0012_ansible_run_triggered_by_nullable"
+down_revision: Union[str, None] = "0011_audit_log"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "ansible_runs", "triggered_by",
+        existing_type=sa.String(36),
+        nullable=True,
+    )
+
+
+def downgrade() -> None:
+    # Re-imposes NOT NULL; will fail if any system-triggered (NULL) rows exist.
+    op.alter_column(
+        "ansible_runs", "triggered_by",
+        existing_type=sa.String(36),
+        nullable=False,
+    )

steward/models/ansible.py

@@ -21,8 +21,10 @@ class AnsibleRun(Base):
     playbook_path: Mapped[str] = mapped_column(String(512), nullable=False)
     inventory_path: Mapped[str] = mapped_column(String(512), nullable=False)
     source_name: Mapped[str] = mapped_column(String(128), nullable=False)
-    triggered_by: Mapped[str] = mapped_column(
-        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False
+    # Nullable: automated runs (alert actions, schedules) have no human actor —
+    # NULL renders as "system". Manual runs still record the triggering user.
+    triggered_by: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="RESTRICT"), nullable=True
     )
     status: Mapped[AnsibleRunStatus] = mapped_column(
         Enum(AnsibleRunStatus), nullable=False, default=AnsibleRunStatus.running

steward/templates/ansible/run_detail.html

@@ -13,6 +13,7 @@
         <span style="color:var(--text-muted);">Playbook</span><span>{{ run.playbook_path }}</span>
         <span style="color:var(--text-muted);">Inventory</span><span>{{ run.inventory_path }}</span>
         <span style="color:var(--text-muted);">Source</span><span>{{ run.source_name }}</span>
+        <span style="color:var(--text-muted);">Triggered by</span><span>{{ triggered_label }}</span>
         <span style="color:var(--text-muted);">Status</span><span style="color:{{ status_color }};font-weight:bold;">{{ run.status.value.upper() }}</span>
         <span style="color:var(--text-muted);">Started</span><span style="color:var(--text-dim);">{{ run.started_at.strftime("%Y-%m-%d %H:%M:%S UTC") }}</span>
         {% if run.finished_at %}

tests/integration/test_ansible_foundation.py

@@ -0,0 +1,101 @@
+"""Integration: the Ansible foundation (task 545).
+
+Proves the two foundation pieces against a live Postgres + a real ansible install:
+  1. ansible-playbook is on PATH (ships in the image / [ansible] extra).
+  2. executor.start_run actually runs a trivial connection:local playbook end to
+     end and records success + output on the AnsibleRun row.
+  3. An AnsibleRun with triggered_by=NULL inserts and round-trips (migration 0012).
+
+Requires STEWARD_DATABASE_URL (the integration CI lane provides it). A fresh app
+is built per test so each test's async work runs on its own event loop with its
+own engine (create_app's internal asyncio.run can't be nested under a running
+loop, so these tests are sync and drive async work via asyncio.run).
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import textwrap
+import uuid
+
+import pytest
+
+pytestmark = pytest.mark.integration
+
+_NEEDS_DB = pytest.mark.skipif(
+    not os.environ.get("STEWARD_DATABASE_URL"),
+    reason="integration test needs a live Postgres (STEWARD_DATABASE_URL)",
+)
+
+
+@pytest.fixture
+def app():
+    if not os.environ.get("STEWARD_DATABASE_URL"):
+        pytest.skip("needs Postgres")
+    from steward.app import create_app
+    # testing=False → runs all migrations (incl. 0012) and gives a real engine.
+    return create_app(testing=False)
+
+
+def test_ansible_playbook_on_path():
+    assert shutil.which("ansible-playbook") is not None
+
+
+@_NEEDS_DB
+def test_null_triggered_run_inserts(app):
+    from sqlalchemy import select
+    from steward.models.ansible import AnsibleRun, AnsibleRunStatus
+
+    run_id = str(uuid.uuid4())
+
+    async def _go():
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                s.add(AnsibleRun(
+                    id=run_id, playbook_path="p.yml", inventory_path="i.ini",
+                    source_name="t", triggered_by=None,
+                    status=AnsibleRunStatus.success,
+                ))
+        async with app.db_sessionmaker() as s:
+            row = (await s.execute(
+                select(AnsibleRun).where(AnsibleRun.id == run_id))).scalar_one()
+            return row.triggered_by
+
+    assert asyncio.run(_go()) is None
+
+
+@_NEEDS_DB
+def test_executor_runs_local_playbook(app, tmp_path):
+    from sqlalchemy import select
+    from steward.ansible import executor
+    from steward.models.ansible import AnsibleRun, AnsibleRunStatus
+
+    (tmp_path / "test.yml").write_text(textwrap.dedent("""\
+        - hosts: localhost
+          connection: local
+          gather_facts: false
+          tasks:
+            - debug:
+                msg: STEWARD_ANSIBLE_OK
+    """))
+    (tmp_path / "inv.ini").write_text("localhost ansible_connection=local\n")
+
+    run_id = str(uuid.uuid4())
+
+    async def _go():
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                s.add(AnsibleRun(
+                    id=run_id, playbook_path="test.yml", inventory_path="inv.ini",
+                    source_name="t", triggered_by=None,
+                    status=AnsibleRunStatus.running,
+                ))
+        await executor.start_run(app, run_id, "test.yml", "inv.ini", str(tmp_path))
+        async with app.db_sessionmaker() as s:
+            return (await s.execute(
+                select(AnsibleRun).where(AnsibleRun.id == run_id))).scalar_one()
+
+    run = asyncio.run(_go())
+    assert run.status == AnsibleRunStatus.success, run.output
+    assert "STEWARD_ANSIBLE_OK" in (run.output or "")