diff --git a/docs/faq.md b/docs/faq.md index 67056888..19f62dc2 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -2,7 +2,7 @@ ## Test notifications -Through the [command line](get-started.md#diun-cli) with: +Through the [command line](usage/cli.md) with: ```shell $ diun --config ./diun.yml --test-notif @@ -11,7 +11,7 @@ $ diun --config ./diun.yml --test-notif Or within a container: ```shell -$ docker-compose exec diun --test-notif +$ docker run --rm -it -v "$(pwd)/diun.yml:/diun.yml" crazymax/diun:latest --config /diun.yml --test-notif ``` ## field docker|swarm uses unsupported type: invalid diff --git a/docs/get-started.md b/docs/get-started.md index a07592b4..333340dc 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -21,96 +21,8 @@ and [File](providers/file.md) providers available * Timezone can be changed * Official [Docker image available](install/docker.md) -## Diun CLI +## Usage -``` -$ ./diun --help -Usage: diun - -Docker image update notifier. More info: https://github.com/crazy-max/diun - -Flags: - --help Show context-sensitive help. - --version - --config=STRING Diun configuration file ($CONFIG). - --timezone="UTC" Timezone assigned to Diun ($TZ). - --log-level="info" Set log level ($LOG_LEVEL). - --log-json Enable JSON logging output ($LOG_JSON). - --log-caller Add file:line of the caller to log output ($LOG_CALLER). - --test-notif Test notification settings. -``` - -Following environment variables can be used in place of flags: - -| Name | Default | Description | -|--------------------|---------------|---------------| -| `CONFIG` | | Diun configuration file | -| `TZ` | `UTC` | Timezone assigned | -| `LOG_LEVEL` | `info` | Log level output | -| `LOG_JSON` | `false` | Enable JSON logging output | -| `LOG_CALLER` | `false` | Enable to add `file:line` of the caller | - -## Quick start with the Docker provider - -Create a `docker-compose.yml` file that uses the official Diun image: - -```yaml -version: "3.5" - -services: - diun: - image: crazymax/diun:latest - volumes: - - "./data:/data" - - "/var/run/docker.sock:/var/run/docker.sock" - environment: - - "TZ=Europe/Paris" - - "LOG_LEVEL=info" - - "LOG_JSON=false" - - "DIUN_WATCH_WORKERS=20" - - "DIUN_WATCH_SCHEDULE=*/30 * * * *" - - "DIUN_PROVIDERS_DOCKER=true" - - "DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=true" - restart: always -``` - -Here we use a minimal configuration to analyze **all running containers** (watch by default enabled) of your **local Docker** instance **every 30 minutes**. - -That's it. Now you can launch Diun with the following command: - -```shell -$ docker-compose up -d -``` - -If you prefer to rely on the configuration file instead of environment variables: - -```yaml -version: "3.5" - -services: - diun: - image: crazymax/diun:latest - volumes: - - "./data:/data" - - "./diun.yml:/diun.yml:ro" - - "/var/run/docker.sock:/var/run/docker.sock" - environment: - - "CONFIG=/diun.yml" - - "TZ=Europe/Paris" - - "LOG_LEVEL=info" - - "LOG_JSON=false" - restart: always -``` - -```yaml -# ./diun.yml - -watch: - workers: 20 - schedule: "*/30 * * * *" - firstCheckNotif: false - -providers: - docker: - watchByDefault: true -``` +* [Command line](usage/cli.md) +* [Basic example](usage/basic-example.md) +* [Configuration](config/index.md) diff --git a/docs/install/binary.md b/docs/install/binary.md index a4bc6149..7f3b4d61 100644 --- a/docs/install/binary.md +++ b/docs/install/binary.md @@ -24,7 +24,7 @@ And extract diun: $ wget -qO- {{ config.repo_url }}releases/download/v{{ git.tag | trim('v') }}/diun_{{ git.tag | trim('v') }}_linux_x86_64.tar.gz | tar -zxvf - diun ``` -After getting the binary, it can be tested with [`./diun --help`](../get-started.md#diun-cli) command and moved to a permanent location. +After getting the binary, it can be tested with [`./diun --help`](../usage/cli.md) command and moved to a permanent location. ## Server configuration diff --git a/docs/install/docker.md b/docs/install/docker.md index 7aecb2bb..032216e8 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -19,6 +19,10 @@ Image: crazymax/diun:latest - linux/s390x ``` +This reference setup guides users through the setup based on `docker-compose`, but the installation of `docker-compose` +is out of scope of this documentation. To install `docker-compose` itself, follow the official +[install instructions](https://docs.docker.com/compose/install/). + ## Volumes | Path | Description | @@ -27,8 +31,6 @@ Image: crazymax/diun:latest ## Usage -Docker compose is the recommended way to run this image. Copy the following `docker-compose.yml` in `/opt/diun/` on your host for example: - ```yaml version: "3.5" diff --git a/docs/migration/v3-to-v4.md b/docs/migration/v3-to-v4.md index 8f5e70b1..35803f1c 100644 --- a/docs/migration/v3-to-v4.md +++ b/docs/migration/v3-to-v4.md @@ -233,7 +233,7 @@ Following the transposition of the configuration into environment variables, the is no longer loaded by default in the official Docker image. If you want to load a configuration file through the Docker image you will have to declare the -[`CONFIG` environment variable](../get-started.md#diun-cli) pointing to the assigned configuration file: +[`CONFIG` environment variable](../usage/cli.md#environment-variables) pointing to the assigned configuration file: ```yaml version: "3.5" diff --git a/docs/usage/basic-example.md b/docs/usage/basic-example.md new file mode 100644 index 00000000..f1d4ba9d --- /dev/null +++ b/docs/usage/basic-example.md @@ -0,0 +1,68 @@ +# Basic example + +In this section we quickly go over a basic docker-compose file to run Diun using the docker provider. + +## Setup + +Create a `docker-compose.yml` file that uses the official Diun image: + +```yaml +version: "3.5" + +services: + diun: + image: crazymax/diun:latest + volumes: + - "./data:/data" + - "/var/run/docker.sock:/var/run/docker.sock" + environment: + - "TZ=Europe/Paris" + - "LOG_LEVEL=info" + - "LOG_JSON=false" + - "DIUN_WATCH_WORKERS=20" + - "DIUN_WATCH_SCHEDULE=*/30 * * * *" + - "DIUN_PROVIDERS_DOCKER=true" + - "DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=true" + restart: always +``` + +Here we use a minimal configuration to analyze **all running containers** (watch by default enabled) of your **local Docker** instance **every 30 minutes**. + +That's it. Now you can launch Diun with the following command: + +```shell +$ docker-compose up -d +``` + +If you prefer to rely on the configuration file instead of environment variables: + +```yaml +version: "3.5" + +services: + diun: + image: crazymax/diun:latest + volumes: + - "./data:/data" + - "./diun.yml:/diun.yml:ro" + - "/var/run/docker.sock:/var/run/docker.sock" + environment: + - "CONFIG=/diun.yml" + - "TZ=Europe/Paris" + - "LOG_LEVEL=info" + - "LOG_JSON=false" + restart: always +``` + +```yaml +# ./diun.yml + +watch: + workers: 20 + schedule: "*/30 * * * *" + firstCheckNotif: false + +providers: + docker: + watchByDefault: true +``` diff --git a/docs/usage/cli.md b/docs/usage/cli.md new file mode 100644 index 00000000..2b773680 --- /dev/null +++ b/docs/usage/cli.md @@ -0,0 +1,38 @@ +# Command Line + +## Usage + +```shell +$ diun [options] +``` + +## Options + +``` +$ diun --help +Usage: diun + +Docker image update notifier. More info: https://github.com/crazy-max/diun + +Flags: + --help Show context-sensitive help. + --version + --config=STRING Diun configuration file ($CONFIG). + --timezone="UTC" Timezone assigned to Diun ($TZ). + --log-level="info" Set log level ($LOG_LEVEL). + --log-json Enable JSON logging output ($LOG_JSON). + --log-caller Add file:line of the caller to log output ($LOG_CALLER). + --test-notif Test notification settings. +``` + +## Environment variables + +Following environment variables can be used in place: + +| Name | Default | Description | +|--------------------|---------------|---------------| +| `CONFIG` | | Diun configuration file | +| `TZ` | `UTC` | Timezone assigned | +| `LOG_LEVEL` | `info` | Log level output | +| `LOG_JSON` | `false` | Enable JSON logging output | +| `LOG_CALLER` | `false` | Enable to add `file:line` of the caller | diff --git a/mkdocs.yml b/mkdocs.yml index 57b07221..4e3a8408 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,8 @@ nav: - With Docker: install/docker.md - From binary: install/binary.md - Linux service: install/linux-service.md + - Usage: + - Command line: usage/cli.md - Configuration: - Overview: config/index.md - .db: config/db.md