Deutsche Version

Back to overview

Watchdog: Installation

This documentation always describes the latest published version.

Watchdog runs as a Docker Compose stack. The repository ships one Compose file each for local development, stage and live. The repository does not describe an installation without Docker.

Requirements

PHP 8.4 and Symfony 8.1 are part of the image, nothing of that is installed on the host.

Installation

Local (development)

1. Clone the repository and switch to the latest release:

git clone https://github.com/markus-michalski/watchdog.git watchdog
cd watchdog
git checkout $(git tag --sort=-version:refname | head -1)
cp .env.example .env.local

2. Set at least APP_SECRET, APP_ADMIN_USER and APP_ADMIN_PASSWORD_HASH in .env.local (see Configuration). Put the hash in single quotes here so Symfony does not treat $ as a variable.
3. Build the image, start the containers and run the migrations:

make local-build

4. Open the app at http://localhost:8087 and Mailpit (mail catcher) at http://localhost:8128.

The development stack mounts the code as a volume. Afterwards make local-up starts and make local-down stops the stack.

Stage

1. Clone the repository to /opt/watchdog, switch to the latest release and create the env file:

git clone https://github.com/markus-michalski/watchdog.git /opt/watchdog
cd /opt/watchdog
git checkout $(git tag --sort=-version:refname | head -1)
cp .env.stage.example .env.stage

2. Fill in .env.stage: APP_SECRET, APP_ADMIN_USER, APP_ADMIN_PASSWORD_HASH (with $$ instead of $), DEFAULT_URI, MAILER_DSN, MAILER_FROM.
3. Build and start:

make stage-build
make stage-up

make stage-up starts the containers and runs pending database migrations. App: 127.0.0.1:8087, Mailpit: 127.0.0.1:8128 on the server.

Live

1. Clone the repository and create the env file:

git clone https://github.com/markus-michalski/watchdog.git /opt/watchdog
cd /opt/watchdog
git checkout $(git tag --sort=-version:refname | head -1)
cp .env.live.example .env.live

2. Fill in .env.live (APP_SECRET, admin credentials, DEFAULT_URI, a real SMTP server in MAILER_DSN, MAILER_FROM).
3. Build and start:

make live-build
make live-up

The app listens on 127.0.0.1:8086. You need a reverse proxy for access over HTTPS, the repository does not ship a proxy configuration.

Generate the password hash

Access consists of exactly one admin user whose hash lives in the env file. Generate the hash like this:

docker run --rm dunglas/frankenphp:1-php8.4-alpine php -r "echo password_hash('yourpassword', PASSWORD_BCRYPT) . PHP_EOL;"

Alternatively, once the stack is running: docker compose -f compose.stage.yml exec app php bin/console security:hash-password.

Bcrypt hashes contain $. Docker Compose reads .env.stage and .env.live, so every $ must be doubled to $$, for example $$2y$$13$$.... Symfony reads .env.local (local), where you put the hash in single quotes instead.

First start

1. Open the app in the browser. The HTTP Basic Auth dialog appears (realm Watchdog), sign in with APP_ADMIN_USER and the password belonging to the hash.
2. Create a client, contacts and checks, see Configuration.
3. For checks on the host (disk, processes, files) register an agent, see Agents.

Update

cd /opt/watchdog
git fetch --tags
git checkout $(git tag --sort=-version:refname | head -1)
make stage-update

On live use make live-update. Both targets rebuild the image, restart the containers, clear the cache and run the migrations. make live-update restarts app first and then worker, scheduler and agent.

Additional mounts (compose.override.yml)

The Makefile merges a local compose.override.yml automatically when it exists. The file is excluded via .gitignore and survives updates. A template ships as compose.override.yml.example.

cp compose.override.yml.example compose.override.yml

Backup

All data lives in the SQLite file /app/var/data.db inside the named volume (watchdog_stage_data on stage, watchdog_data on live and local). Stop worker and scheduler first to get a consistent copy.

docker compose -f compose.live.yml stop worker scheduler
docker compose -f compose.live.yml cp app:/app/var/data.db ./data.db.bak
docker compose -f compose.live.yml start worker scheduler

Uninstall

Afterwards you can delete /opt/watchdog including .env.stage or .env.live. Remove the agent entries and tokens in the UI under Agents beforehand.