Skip to content
Damdit Docs

Several websites and schedules

damdit.yml lists the websites a Damdit image audits, each with its own settings. run audits them one after another. serve keeps running and audits each one at its own time. Each website keeps its own history, so every run says what is New, Resolved or Reappeared since the run before.

damdit.yml

Section titled “damdit.yml”
state: ./damdit-state # where each website keeps its history, runs and reports
sites:
  - name: Example
    url: https://example.com
    schedule: weekly mon 06:00
    reports: [client.pdf]
    failOn: [new, reappeared]
    failSeverity: high


  - name: Shop
    url: https://shop.example.com
    pages: 200
    schedule: daily 03:00
    pageSpeed: true
    webflow: { site: 64ab12…, tokenEnv: DAMDIT_WEBFLOW_TOKEN_SHOP }
    reports: [client.pdf, developer.html]


  - name: Staging
    url: https://staging.example.com
    access: { kind: basic, usernameEnv: STAGING_USER, passwordEnv: STAGING_PASSWORD }
Key What it does
name The website’s name. It also names its folder in state.
url The address to audit.
pages Render at most this many pages. Optional.
language The language of reports, en-US by default.
schedule When serve audits it: daily HH:MM, weekly mon HH:MM (mon to sun) or monthly D HH:MM (day 1 to 28).
pageSpeed true to use PageSpeed Insights, with the key in DAMDIT_PAGESPEED_KEY.
webflow The Webflow module: site is the site ID, tokenEnv the variable that holds its token (DAMDIT_WEBFLOW_TOKEN by default).
access For a locked website: kind is basic, vercel, cloudflare or webflow, and optional keys name the variables that hold the access (see below).
reports Reports for people after each run, as in --report.
failOn new, reappeared or both: run exits with code 9 when they appear.
failSeverity With failOn, count only issues of this severity or higher.

Secrets never go in the file. Damdit names any missing variable before the first audit.

Locked websites

Section titled “Locked websites”

access names the kind of lock and, optionally, the environment variables that hold the access. Without them, the variables of audit apply:

kind Keys and their defaults
basic usernameEnv (DAMDIT_SITE_USERNAME), passwordEnv (DAMDIT_SITE_PASSWORD)
vercel secretEnv (DAMDIT_VERCEL_BYPASS)
cloudflare clientIdEnv (DAMDIT_CF_ACCESS_CLIENT_ID), clientSecretEnv (DAMDIT_CF_ACCESS_CLIENT_SECRET)
webflow passwordEnv (DAMDIT_WEBFLOW_PASSWORD)

Variable names are capitals, digits and _. Any other key, such as password or secret, is refused, so the access itself can’t end up in the file. Name different variables when several websites have different access. A website without access gets none, even when the default variables are set. When the access is missing or didn’t open the website, its audit fails and the message names the variables to pass or check.

run

Section titled “run”
Terminal window
docker run --rm -e DAMDIT_CI_KEY -v "$PWD:/work" damdit/damdit run
  • --config FILE: another file than damdit.yml.
  • --site NAME: audit only this website.
  • --format json: the results as JSON.

run exits with 1 when an audit failed, with 9 when a website hit its failOn, and with 0 otherwise. Each audit counts toward the 200 a day.

serve

Section titled “serve”
Terminal window
docker run -d --restart unless-stopped --name damdit \
  --env-file .env -v "$PWD:/work" damdit/damdit serve
  • Each website runs at its schedule. Websites due at the same time run one after another.
  • serve reads damdit.yml again before every wait, so an edit applies without a restart.
  • Times are the container’s time: UTC unless you set TZ, for example -e TZ=Europe/Prague.
  • A run missed while the container was stopped is not made up. The website waits for its next time.
  • serve-status.json in the state folder says when each website runs next and how its last run ended.
  • docker stop damdit stops it cleanly.

The state folder

Section titled “The state folder”
damdit-state/
  example/
    history.sqlite       the issue history across runs
    last.dpk             the latest run, the baseline of the next
    runs/<time>.dpk      the last 20 runs
    reports/<time>/      the reports of each run

Keep the folder between runs: in CI, cache it (see Pipelines). Without it, every run starts without history and reports nothing as New.