onesystems/onerun repository overview

⁠OneRun

Modern, lightweight, self-hosted infrastructure automation by OneSystems GmbH⁠.

OneRun runs Ansible playbooks from Git with a clean UI, live logs, encrypted credentials, schedules, and notifications — a practical alternative to heavier orchestration stacks. One image covers everything from a single container (Lite) to Postgres and remote runners (Standard / Scale).

⁠Editions: Community & Pro

OneRun ships as one Docker image. Without a license key the instance runs as Community. Activate a Pro key under Administration → License to unlock additional features.

CLI backup / restore remains available in both editions. Order or renew Pro at the shop⁠.

⁠Image

docker pull onesystems/onerun:1.0.0

Tags: <version> and 1.0 (releases do not use latest).

The image includes the API, admin UI, ansible-core, and ansible-galaxy. Collections and roles are installed at run time from requirements.yml (or instance defaults), not baked into the image.

⁠Operating modes

Same product and image — only persistence and where jobs execute change.

Switch by configuration (ONERUN_POSTGRES_ENABLED / Postgres env, runner token, Redis URL).

Migration: Lite → Standard without reinstall (same master key, backup, then onerun migrate-sqlite-to-postgres). Standard → Scale by registering remote runners (Pro).

⁠Quick start

⁠Lite (Community-friendly)

services:
  onerun:
    image: onesystems/onerun:1.0.0
    user: "1000:1000"
    command: ["serve"]
    environment:
      TZ: Europe/Zurich
      ONERUN_ENV: production
      ONERUN_PUBLIC_URL: https://onerun.example.com
      ONERUN_MASTER_KEY: "change-me-to-a-long-random-secret!!"
      ONERUN_ADMIN_EMAIL: [email protected]
      ONERUN_ADMIN_PASSWORD: "change-me-strong-password"
      ONERUN_ADMIN_NAME: Administrator
      ONERUN_TRUSTED_PROXIES: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    volumes:
      - onerun_data:/data
    ports:
      - "8091:8080"

volumes:
  onerun_data:

docker compose up -d

The bootstrap admin from ONERUN_ADMIN_* is created only when no users exist. Changing those variables later does not update an existing account.

⁠Standard (App + Postgres)

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: onerun
      POSTGRES_PASSWORD: "change-me"
      POSTGRES_DB: onerun
    volumes:
      - postgres_data:/var/lib/postgresql/data

  onerun:
    image: onesystems/onerun:1.0.0
    user: "1000:1000"
    command: ["serve"]
    depends_on:
      - postgres
    environment:
      TZ: Europe/Zurich
      ONERUN_ENV: production
      ONERUN_PUBLIC_URL: https://onerun.example.com
      ONERUN_MASTER_KEY: "change-me-to-a-long-random-secret!!"
      ONERUN_ADMIN_EMAIL: [email protected]
      ONERUN_ADMIN_PASSWORD: "change-me-strong-password"
      ONERUN_POSTGRES_ENABLED: "true"
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_USER: onerun
      POSTGRES_PASSWORD: "change-me"
      POSTGRES_DB: onerun
      POSTGRES_SSLMODE: disable   # use require when TLS is available
    volumes:
      - onerun_data:/data
    ports:
      - "8091:8080"

volumes:
  onerun_data:
  postgres_data:

⁠Scale (remote runner, Pro)

1. Activate a Pro license.
2. In the UI: Admin → Runners — create a runner and copy the token once.
3. Start another container from the same image with command: ["runner"]:

  onerun-runner:
    image: onesystems/onerun:1.0.0
    user: "1000:1000"
    command: ["runner"]
    # Required on images that still probe :8080 (runner has no HTTP server).
    healthcheck:
      disable: true
    environment:
      ONERUN_URL: http://onerun:8080
      ONERUN_RUNNER_TOKEN: "paste-token-here"
      ONERUN_RUNNER_LABELS: docker,remote
      ONERUN_DATA_DIR: /data
      ONERUN_MASTER_KEY: "same-as-server"
    volumes:
      - onerun_runner_data:/data

Without disabling (or updating) the healthcheck, Swarm marks the task unhealthy and restarts it in a loop.

Optional Redis (wake queue): set a strong REDIS_PASSWORD, point ONERUN_REDIS_URL at redis://:<password>@redis:6379/0, and set ONERUN_REDIS_HMAC_SECRET in production.

⁠Container commands

docker compose exec onerun onerun backup /tmp/onerun-backup.tar.gz
docker compose run --rm onerun migrate-sqlite-to-postgres --dry-run

⁠Configuration backup (Pro UI)

Admin → System → Configuration backup:

• Writes to ONERUN_BACKUP_DIR (Compose volume /backup)
• config/*.yaml — readable configuration without secret values
• secrets.age — credentials / tokens encrypted with a dedicated backup passphrase (age⁠)
• Schedule: daily / weekly / monthly, retention by max versions

age -d -o secrets.json /backup/onerun-config-…/secrets.age

⁠Core features

• Projects & Git — SSH/HTTPS repositories, branches/tags, host-key handling, connection tests; playbooks from Git as source of truth
• Encrypted key store — SSH keys, passwords, vault / become secrets, tokens (encrypted at rest with ONERUN_MASTER_KEY)
• Inventories & tasks — Git or local inventory, extra vars, tags/skip-tags, check/diff, timeouts, simulation (check mode)
• Runs — Live and raw logs with secret masking, cancel/rerun, summaries, retention
• Schedules — Cron with timezone, pause, no overlapping runs for the same task
• Auth — Local users, MFA (TOTP + recovery), optional SMTP for email OTP recovery; SSO and API tokens with Pro
• RBAC — Project roles and admin separation
• Notifications — SMTP, ntfy, Nextcloud Talk (and related channels as configured)
• Ops — Health check, backup/restore CLI, SQLite → Postgres migration, audit trail

⁠Environment variables

⁠General

⁠Bootstrap admin (empty database only)

⁠Database

⁠Redis (optional, Scale / Pro)

⁠Remote runner agent (Pro)

⁠SMTP (optional; MFA / recovery mail)

⁠OpenID Connect (SSO, Pro)

Configure issuer, client ID/secret (and options) in Admin → System. Redirect URI:

{ONERUN_PUBLIC_URL}/api/v1/auth/oidc/callback

Local admin password login remains available as break-glass unless ONERUN_OIDC_ONLY=true.

⁠First steps after install

1. Open the UI — complete /setup if prompted.
2. Sign in and finish MFA (TOTP). Store recovery codes; configure SMTP if you want email OTP recovery.
3. Create a repository, credential, inventory, and task.
4. Run a simulation, then a real run; confirm live logs and secret masking.
5. Optionally add schedules and notification profiles.
6. For Pro features: Administration → License and activate your key.

⁠Production security checklist

• Set ONERUN_ENV=production and a unique ONERUN_MASTER_KEY (long random string). Losing the key means encrypted credentials cannot be recovered.
• Do not use Compose/dev defaults for admin password, master key, Postgres, or Redis.
• Persist /data on a volume; back up the volume and the master key together.
• Terminate TLS at a reverse proxy; set ONERUN_TRUSTED_PROXIES to your edge CIDRs.
• Prefer POSTGRES_SSLMODE=require when the database supports TLS.
• Do not publish Redis to the public internet; always use a password in ONERUN_REDIS_URL.
• Keep ONERUN_ANSIBLE_HOST_KEY_CHECKING=true unless you have a controlled exception.
• Restrict who can manage repositories, webhooks, and system settings.
• Rotate runner tokens and API tokens if leaked; treat runner hosts as trusted execution environments.

⁠Health check

curl -fsS https://onerun.example.com/api/health

A healthy response includes "status":"ok" and database connectivity.

⁠Author

OneSystems GmbH⁠
[email protected]⁠

⁠License

© OneSystems GmbH. Distributed as container images via Docker Hub⁠.
Community edition is free to run; Pro unlocks additional features via a license key from the OneSystems shop⁠.
For OEM or special licensing, contact OneSystems GmbH⁠.