onesystems/step-ca-to-bookstack repository overview

⁠🔗 Step-CA to Bookstack

This container reads your Smallstep step-ca Badger database with step-badger and automatically updates a BookStack page with a clear certificate list.

⁠What you get

• Two tables on your BookStack page:
  • Expired (includes REVOKED)
  • Active
• Sorted by End (expiry) ascending
• Row highlighting close to expiry (yellow/red; days & colors are configurable)
• Time format: dd.mm.yyyy hh:mm (local time)

⁠Prerequisites

1. BookStack API token (Admin → Settings → API → Create Token). Note Token ID and Token Secret.
2. A BookStack page to host the tables. Note the page ID (visible in the URL, e.g. /pages/123).
3. step-ca data directory mounted into the container with the Badger DB (files like MANIFEST, KEYREGISTRY, *.sst, *.vlog). Example: host /docker/step/ca/db → container /step/db.

⁠Quick start (Docker Compose)

Create or open docker-compose.yml and add this service:

services:
  sync:
    image: onesystems/step-ca-to-bookstack:latest
    environment:
      # When to sync? (cron, container local time)
      CRON_SCHEDULE: "5 2 * * *"   # daily 02:05
      TZ: "Europe/Zurich"

      # BookStack API
      BOOKSTACK_URL: "https://wiki.example.com"
      BOOKSTACK_PAGE_ID: "123"          # your page ID
      BOOKSTACK_TOKEN_ID: "<token-id>"
      BOOKSTACK_TOKEN_SECRET: "<token-secret>"
      # Alternative to the two lines above:
      # BOOKSTACK_API_KEY: "<token-id>:<token-secret>"

      # step-ca DB path inside the container
      STEP_DB_DIR: "/step/db"

      # (Optional) internal DB copy to avoid locks
      DB_SNAPSHOT: "true"
      TMP_BASE: "/tmp"

      # (Optional) row colors / thresholds
      WARN_DAYS: "30"         # yellow when ≤ 30 days left
      CRIT_DAYS: "10"         # red    when ≤ 10 days left
      WARN_BG: "#fff6bf"
      CRIT_BG: "#ffd6d6"

      # (Optional) title above the tables (leave empty to hide)
      TABLE_TITLE: "step-ca certificates"

    volumes:
      - /docker/step/ca:/step:ro   # must contain directory "db"
    restart: unless-stopped

Start the service:

docker compose up -d

Watch logs:

docker compose logs -f sync

⁠What appears on the page?

• A timestamp line: Generated: …
• Expired table (expired or revoked certificates)
• Active table (currently valid certificates)
• Columns: Subject/CN, SANs, Serial, Start, End, Days Left, Provisioner, Status
• Row colors:
  • Yellow when Days Left ≤ WARN_DAYS
  • Red when Days Left ≤ CRIT_DAYS

⁠Environment variables

⁠Run once now (ad‑hoc)

# Run the sync script inside the running container
docker exec -it <container> /usr/bin/python3 /app/sync.py

# Tail cron output
docker exec -it <container> sh -c 'tail -n 200 /var/log/cron.log'

⁠Troubleshooting

“Cannot acquire directory lock … Another process is using this Badger database.”
This is expected while step-ca is running. Keep DB_SNAPSHOT=true and ensure there is free space under TMP_BASE (default /tmp).

Empty columns / missing values
JSON field names from step-badger may vary. The script uses a tolerant, deep lookup for common keys. If values remain empty, please verify that your mount contains the Badger files and check logs with docker compose logs -f sync.

BookStack 401/403
Double-check BOOKSTACK_URL, BOOKSTACK_PAGE_ID, and the token’s permissions. The token must be allowed to update the target page.

⁠Customize

• Schedule: CRON_SCHEDULE (cron syntax)
• Title: set TABLE_TITLE to empty to hide
• Colors / thresholds: tune WARN_DAYS, CRIT_DAYS, WARN_BG, CRIT_BG

⁠Update & remove

Update:

docker compose pull sync
docker compose up -d

Stop & remove:

docker compose down

⁠Security

• Keep tokens in a safer place, e.g. a .env file or Docker secrets, rather than hard-coding them in compose.
• The container accesses your step-ca data read-only.

⁠Author

• Michael Kleger
  OneSystems GmbH⁠
  [email protected]⁠

⁠License

MIT License – free for commercial and private use.

⁠Credits

• step-badger by Smallstep community.
• This mailer uses the same snapshot & parsing approach as our BookStack sync for step-ca.