-
-
Notifications
You must be signed in to change notification settings - Fork 5
Usage
Command line arguments can be viewed by running:
docker run --rm ghcr.io/gmt2001/ouroboros --help
All command line arguments can be substituted with an environment variable. command line options are kebab-case and environment variables are SCREAMING_CASE. E.g.
--docker-sockets vs. DOCKER_SOCKETS
. All examples will be given as environment variables for adocker run
as --help will show command line examples
Type: Boolean - Interrupting
Command Line: -h, --help
Shows the help message then exits
Type: Boolean - Interrupting
Command Line: -v, --version
Shows the current version number then exits
Type: List - Space separated
Command Line: -d, --docker-sockets
Environment Variable: DOCKER_SOCKETS
Default: unix://var/run/docker.sock
Example: -e DOCKER_SOCKETS="unix://var/run/docker.sock tcp://192.168.1.100:2376"
Allows you to define a list of docker sockets. If defined, it does not include the local socket by default.
Type: Boolean
Command Line: -t, --docker-tls
Environment Variable: DOCKER_TLS
Default: False
Example: -e DOCKER_TLS=true
Enables docker TLS secure client connections by certificate
Example cert structure:
/etc/docker/certs.d/ <-- Certificate directory
└── localhost:5000 <-- socket as defined in config after //
├── client.cert <-- Client certificate
├── client.key <-- Client key
└── ca.crt <-- CA certificate
and would be mounted something like
-v /etc/docker/certs.d:/etc/docker/certs.d
Type: Boolean
Command Line: -T, --docker-tls-verify
Environment Variable: DOCKER_TLS_VERIFY
Default: False
Example: -e DOCKER_TLS_VERIFY=true
Enables verifying docker TLS secure client connections by certificate
Type: Integer
Command Line: -i, --interval
Environment Variable: INTERVAL
Default: 300
Example: -e INTERVAL=300
The interval in seconds between checking for updates. There is a hard-coded 30 second minimum. Anything lower than that will set to 30. Ignored if --cron
is defined.
Type: String
Command Line: -C, --cron
Environment Variable: CRON
Default: None
Example: -e CRON="*/5 * * * *"
The schedule defined when to check for updates. The cron schedule will run according to the timezone from --timezone
. If not defined, --interval
will be used instead.
Type: String - Choice
Command Line: -l, --log-level
Environment Variable: LOG_LEVEL
Choices:
- debug
- info
- warn
- error
- critical
Default: info
Example: -e LOG_LEVEL=info
Sets your logging verbosity level.
Type: Boolean
Command Line: -u, --self-update
Environment Variable: SELF_UPDATE
Default: False
Example: -e SELF_UPDATE=true
Let ouroboros update itself in addition to your other containers. Self updates require the the container to be named either ouroboros or ouroboros-updated and will alternate the former names for updates. Self updates will wipe update counters for notifications, unless the Save Counters option is enabled.
Type: Boolean - Interrupting
Command Line: -o, --run-once
Environment Variable: RUN_ONCE
Default: False
Example: -e RUN_ONCE=true
Ouroboros will only do a single pass of all container checks, and then exit. This is a great way to granularly control scheduling with an outside scheduler like cron. If during the single pass ouroboros has to self-update, it will do another full pass after updating itself to ensure that all containers were checked. Overrides --interval
and --cron
.
Type: Boolean
Command Line: -A, --dry-run
Environment Variable: DRY_RUN
Default: False
Example: -e DRY_RUN=true
Ouroboros will only simulate container updates, but will not perform the actions. Best for testing configurations, seeing what updates would be applied. Best used with run-once
.
Type: Boolean
Command Line: -mo, --monitor-only
Environment Variable: MONITOR_ONLY
Default: False
Example: -e MONITOR_ONLY=true
Ouroboros will only send update available notifications, but will not perform the actual updates. Best for situations where you want to know about updates, but decide for yourself when to apply them.
Type: String
Command Line: -la, --language
Environment Variable: LANGUAGE
Default: en
Example: -e LANGUAGE=es
Set the language of the translation.
Type: String
Command Line: -tz, --timezone
Environment Variable: TZ
Default: UTC
Example: -e TZ=America/Chicago
Set the timezone of notifications and cron. See Timezone Configuration.
Type: Integer
Command Line: --docker-timeout
Environment Variable: DOCKER_TIMEOUT
Default: 60
Example: -e DOCKER_TIMEOUT=120
Docker client timeout, in seconds.
Type: Boolean
Command Line: -S, --swarm
Environment Variable: SWARM
Default: false
Example: -e SWARM=true
Put ouroboros in swarm mode. If set true
, ouroboros will monitor and update Docker Swarm Services instead of individual Containers.
Type: List - Space separated
Command Line: -m, --monitor
Environment Variable: MONITOR
Default: All
Example: -e MONITOR="nginx telegraf portainer"
Define a list of containers you would like to monitor instead of all containers. If a container is also listed in --ignore
, then the ignore takes priority. If a container is listed that does not match the name of currently running containers, it will be ignored.
Type: List - Space separated
Command Line: -n, --ignore
Environment Variable: IGNORE
Default: None
Example: -e IGNORE="mariadb influxdb mongo postgres"
Define a list of containers you would like to ignore updates for. Overrides --monitor
. If a container is listed that does not match the name of currently running containers, it will be ignored.
Type: Boolean
Command Line: -k, --label-enable
Environment Variable: LABEL_ENABLE
Default: False
Example: -e LABEL_ENABLE=true
If a container has a com.ouroboros.enable
label, only watch it if it is set to true
. Supersedes monitor/ignore in precedence. This can be achieved by setting LABEL com.ouroboros.enable="false"
in your Dockerfile or passing the label during creation of the container with docker run -d --label=com.ouroboros.enable="false" person/image:tag
. See Labels for a list of all available labels.
Type: Boolean
Command Line: -m, --labels-only
Environment Variable: LABELS_ONLY
Default: False
Example: -m LABELS_ONLY=true
This flag allows a more strict control over ouroboros's updates. If the container does not have a com.ouroboros.enable
label, it will be ignored completely. If label_enable is not true, this option is ignored. See Labels for a list of all available labels.
Type: Boolean
Command Line: -c, --cleanup
Environment Variable: CLEANUP
Default: False
Example: -e CLEANUP=true
Remove the old images after updating. If you have multiple containers using the same image, it will ensure all containers are updated before successfully removing the image.
Type: Boolean
Command Line: -L, --latest-only
Environment Variable: LATEST_ONLY
Default: False
Example: -e LATEST_ONLY=true
Pull the :latest
tags and update all containers to it, regardless of the current tag the container is running as. If there is no :latest
tag, the existing tag will be used.
Type: String
Command Line: -r, --repo-user
Environment Variable: REPO_USER
Default: None
Example: -e REPO_USER=johndoe1970
Define a username for repository authentication. Will be ignored without defining a repository password.
Type: String
Command Line: -R, --repo-pass
Environment Variable: REPO_PASS
Default: None
Example: -e REPO_PASS=0791eodnhoj
Define a password for repository authentication. Will be ignored without defining a repository username.
Type: Boolean
Command Line: -sc, --save-counters
Environment Variable: SAVE_COUNTERS
Default: False
Example: -e SAVE_COUNTERS=true
Saves and restores the total_updated
counter inserted into Apprise notifications when performing a self-update
Type: String - Choice
Command Line: -D, --data-export
Environment Variable: DATA_EXPORT
Choices:
- prometheus
- influxdb
Example:
-e DATA_EXPORT=influxdb
Enables exporting metric data to your chosen application. If you choose Prometheus, and self update, host port bindings will not persist. It is recommended to reverse proxy your exporter through nginx. If you choose influxdb, you must set influx database at minimum.
Full Example:
-e PROMETHEUS_ADDR=0.0.0.0 \
-e PROMETHEUS_PORT=3579
See Prometheus Metrics for more insight
Type: String
Command Line: -a, --prometheus-addr
Environment Variable: PROMETHEUS_ADDR
Default: 127.0.0.1
Example: -e PROMETHEUS_ADDR=0.0.0.0
Bind address for prometheus exporter to attach to.
Type: Integer
Command Line: -p, --prometheus-port
Environment Variable: PROMETHEUS_PORT
Default: 8000
Example: -e PROMETHEUS_PORT=3579
Bind port for prometheus exporter to attach to.
Full Example:
-e INFLUX_URL=influx.domain.tld \
-e INFLUX_PORT=443 \
-e INFLUX_USERNAME=ouroboros \
-e INFLUX_PASSWORD=soroboruo \
-e INFLUX_DATABASE=ouroboros \
-e INFLUX_SSL=true \
-e INFLUX_VERIFY_SSL=true
Type: String
Command Line: -I, --influx-url
Environment Variable: INFLUX_URL
Default: 127.0.0.1
Example: -e INFLUX_URL=192.168.1.100
URL influxdb is listening on
Type: Integer
Command Line: -P, --influx-port
Environment Variable: INFLUX_PORT
Default: 8086
Example: -e INFLUX_PORT=8123
Port influxdb is listening on
Type: String
Command Line: -U, --influx-username
Environment Variable: INFLUX_USERNAME
Default: root
Example: -e INFLUX_USERNAME=ouroboros
Username to authenticate to influx with.
Type: String
Command Line: -x, --influx-password
Environment Variable: INFLUX_PASSWORD
Default: root
Example: -e INFLUX_PASSWORD=soroboruo
Password to authenticate to influx with.
Type: String
Command Line: -X, --influx-database
Environment Variable: INFLUX_DATABASE
Default: None
Example: -e INFLUX_DATABASE=ouroboros
Database to save data points to. Not set and required if using influxdb.
Type: Boolean
Command Line: -s, --influx-ssl
Environment Variable: INFLUX_SSL
Default: None
Example: -e INFLUX_SSL=true
Use SSL when connecting to influxdb. (mainly used when influxdb is behind an https reverse proxy)
Type: Boolean
Command Line: -V, --influx-verify-ssl
Environment Variable: INFLUX_VERIFY_SSL
Default: False
Example: -e INFLUX_VERIFY_SSL=true
Verify the ssl certificate used when connecting to influxdb. only used in conjunction with influx ssl
Type: List - Space separated
Command Line: -N, --notifiers
Environment Variable: NOTIFIERS
Default: None
Example: -n NOTIFIERS="mailtos://myUsername:myPassword@gmail.com?to=receivingAddress@gmail.com jsons://webhook.site/something"
Ouroboros uses apprise to support a large variety of notification platforms.
Notifications are sent per socket, per run. The notification contains the socket, the containers updated since last start, and a list of containers updated this pass with from/to SHA.
More information can be found in the notifications wiki.
Type: Boolean
Command Line: --skip-startup-notifications
Environment Variable: SKIP_STARTUP_NOTIFICATIONS
Default: False
Example: --skip-startup-notifications
Doesn't send startup notifications if arg is passed.
-
com.ouroboros.enable
Example:
com.ouroboros.enable=true
Used for Label Enable -
com.ouroboros.depends_on
Example:
com.ouroboros.depends_on=postgres,redis
To simulate docker-compose depends_on functionality. If defined on any containers (by container name), all referenced containers will be turned off before the update process and then turned back on after the update process.
-
com.ouroboros.hard_depends_on
Example:
com.ouroboros.hard_depends_on=postgres,redis
Same as above with the exception that it will recreate the container instead of just turning it off/ton -
com.ouroboros.stop_signal
Example:
com.ouroboros.stop_signal=SIGKILL
Define a stop signal to send to the container instead of SIGKILL. Can be string or int.
You can provide a docker env file to supplement a config file with all the above listed arguments by utilizing the supported environment variables.
docker run -d --name ouroboros \
--env-file ouroboros.env \
-v /var/run/docker.sock:/var/run/docker.sock \
gmt2001/ouroboros
Sample ouroboros.env
:
DOCKER_SOCKETS=tcp://localhost:2375
INTERVAL=60
MONITOR="container_1 container_2"
Ouroboros keeps track of containers being updated and how many are being monitored. Said metrics are exported using prometheus. You can also bind the http server to a different interface for systems using multiple networks. --prometheus-port
and --prometheus-addr
can run independently of each other without issue.
Prometheus exporter will not be reachable by default inside of a container. You will need to intentionally bind to
0.0.0.0
for docker network interfaces to be able to reach the exporter the host network. This was done intentionally for security reasons.
Bind Address default is
127.0.0.1
Port Default is
8000
docker run -d --name ouroboros \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 8000:8000 gmt2001/ouroboros --data-export prometheus --prometheus-addr 0.0.0.0
You should then be able to see the metrics at http://localhost:8000/
Example text from endpoint:
# HELP containers_updated_total Count of containers updated
# TYPE containers_updated_total counter
containers_updated_total{container="all"} 2.0
containers_updated_total{container="alpine"} 1.0
containers_updated_total{container="busybox"} 1.0
# TYPE containers_updated_created gauge
containers_updated_created{container="all"} 1542152615.625264
containers_updated_created{container="alpine"} 1542152615.6252713
containers_updated_created{container="busybox"} 1542152627.7476819
# HELP containers_being_monitored Count of containers being monitored
# TYPE containers_being_monitored gauge
containers_being_monitored 2.0