Watchdog: Configuration
Environment variables with defaults and how to set up clients, contacts, URLs and checks in the UI. Interval, daily run time, retention and runner.
Watchdog: Configuration
Environment variables
The values live per environment in .env.local (local), .env.stage or .env.live. The Default column shows the value from the bundled .env where one is set.
| Variable | Default | Meaning |
|---|---|---|
APP_ENV |
dev |
Symfony environment. compose.live.yml sets prod, compose.stage.yml and the local stack set dev (with debug tooling such as the profiler and debug toolbar, which are reachable without signing in, see Security) |
APP_DEBUG |
0 |
Debug mode |
APP_SECRET |
empty | Secret key of the app, required. Generate with php -r "echo bin2hex(random_bytes(32));" |
DATABASE_URL |
sqlite:///%kernel.project_dir%/var/data.db |
Database. SQLite is the intended setup, no separate database container is needed |
MESSENGER_TRANSPORT_DSN |
doctrine://default?auto_setup=0 |
Queue for checks and emails, stored in the same database |
APP_ADMIN_USER |
admin |
User name of the single admin account |
APP_ADMIN_PASSWORD_HASH |
not-set |
Bcrypt hash of the admin password, see Installation |
MAILER_DSN |
smtp://mailpit:1025 |
SMTP access for alert emails, e.g. smtp://user:pass@smtp.example.com:587 |
MAILER_FROM |
watchdog@example.com |
Sender address of the alert emails |
DEFAULT_URI |
http://localhost:8087 |
Base URL for generating URLs outside web requests. The alert emails contain no link to the app |
TRUSTED_PROXIES |
empty | IP of the reverse proxy, never *. compose.stage.yml and compose.live.yml hard-set the value to REMOTE_ADDR, so an entry in the env file has no effect there |
WATCHDOG_AGENT_TOKEN |
empty | Token of the host agent, see Agents |
WATCHDOG_DASHBOARD_URL |
empty | Agents only: dashboard base URL without a trailing slash |
HOST_ROOT |
empty | Agents only: path prefix under which the host filesystem is mounted, e.g. /host/root |
DOCKER_GID |
995 |
Compose only: group ID of the Docker socket for worker and scheduler (group_add) |
Time zone: the Dockerfile and the Compose files set Europe/Berlin. Times in the UI, the daily run time and the retention cleanup all refer to this time zone.
Setup order in the UI
The navigation consists of Dashboard, Clients, Contacts and Agents.
- Create contacts under Contacts: name and email address. The email address is unique.
- Create a client under Clients: Name, Active and Alert contacts (the contacts to notify).
- On the client page, add the monitored URLs with + Add URL.
- Create the checks with + Add check.
Client
| Field | Meaning |
|---|---|
| Name | Display name, used in subject and body of the alert emails |
| Active | Inactive clients are not scheduled and not handed out to agents. Manual Run now still works |
| Alert contacts | Recipients of the alert emails for all checks of this client. Without contacts Watchdog sends no emails |
Deleting a client also deletes its checks.
URL
| Field | Meaning |
|---|---|
| URL | Must be a valid URL with a top-level domain, the form rejects host names without a dot such as http://localhost |
| Label (optional) | Short name for dropdowns and emails, defaults to the URL |
| BasicAuth username / password | Optional credentials sent by HTTP and HTTP Content checks. The password is stored unencrypted in the database |
Check
| Field | Default | Meaning |
|---|---|---|
| Check type | One of the check types | |
| Runner | Dashboard (Network) | Dashboard (Network) runs the check in the worker container, Agent (Local) on an agent. The form restricts which runners a type allows via JavaScript |
| Agent | Only for runner Agent: the executing agent | |
| Interval | 5 min | Time between two runs in days, hours and minutes, at least 1 minute |
| Daily at (optional) | empty | Time of day HH:MM. When set, the check runs once a day at this time and the interval is ignored |
| Keep results for (days) | empty | Retention of results. Empty keeps all results |
| Active | on | Inactive checks are not scheduled |
The type-specific fields are listed on the page of each check type. Fields you leave empty are replaced by the defaults of the type when the check runs.
The interval is a guideline with a small tolerance. The scheduler tests dashboard checks once a minute and starts a check as soon as at least the interval minus 30 seconds has passed since the last result. The agent tests every 30 seconds and starts a check once the interval minus 5 seconds is reached. There is no interval below one minute.
Result retention
Every day at 03:00 the scheduler deletes, for each check that has a retention set, all results older than the given number of days. Checks without a value keep all results. A check running every five minutes produces about 288 results per day, so set the retention deliberately.
Legal texts
The imprint and privacy notice in the footer are placeholders. Replace the files templates/legal/impressum.html.twig and templates/legal/datenschutz.html.twig with your own texts. The templates ship as *.dist, and make setup creates missing files from them.
Other settings
| Topic | Value |
|---|---|
| API rate limit | 60 requests per minute and IP for all paths under /api/ |
| Failed messages | Up to 3 retries, each with a doubled delay, then the failed transport |
| Container restart | Worker and scheduler exit after 3600 seconds or 128 MB of memory and are restarted by restart: unless-stopped |