umputun / updater

Updater is a simple web-hook-based receiver executing things via HTTP requests and invoking remote updates without exposing any sensitive info, like ssh keys, passwords, etc. The updater is usually called from CI/CD system (i.e., Github action), and the actual http call looks like curl https://<server>/update/<task-name>/<access-key>. Alternatively, the updater can be called with POST method and the payload can be passed as JSON, i.e. curl -X POST -d '{"task":"remark42-site", "secret":"123456"}' https://example.com/update

List of tasks defined in the configuration file, and each task has its custom section for the command.

Example of updater.yml:

tasks:

  - name: remark42-site
    command: |
      echo "update remark42-site"
      docker pull ghcr.io/umputun/remark24-site:master
      docker rm -f remark42-site
      docker run -d --name=remark42-site

  - name: feed-master
    command: |
      echo "update feed-master"
      docker pull umputun/feed-master
      docker restart feed-master

By default the update call synchronous but can be switched to non-blocking mode with async query parameter, i.e. curl https://example.com/update/remark42-site/super-seecret-key?async=1. To request the async update with POST, async=true should be used in the payload, i.e. curl -X POST -d '{"task":"remark42-site", "secret":"123456", "async":true}' https://example.com/update

Install

Updater distributed as multi-arch docker container as well as binary files for multiple platforms. Container has the docker client preinstalled to allow the typical "docker pull & docker restart" update sequence.

Containers available on both github container registry (ghcr) and docker hub

This is an example of updater usage inside of the docker compose. It uses reproxy as the reversed proxy, but any other (nginx, apache, haproxy, etc) can be used as well.

services:
  
  reproxy:
    image: ghcr.io/umputun/reproxy:master
    restart: always
    hostname: reproxy
    container_name: reproxy
    logging: &default_logging
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    ports:
      - "80:8080"
      - "443:8443"
    environment:
      - TZ=America/Chicago
      - DOCKER_ENABLED=true
      - SSL_TYPE=auto
      - [email protected]
      - SSL_ACME_FQDN=jess.umputun.com,echo.umputun.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./var/ssl:/srv/var/ssl

  echo:
    image: ghcr.io/umputun/echo-http
    hostname: echo
    container_name: echo
    command: --message="echo echo 123"
    logging: *default_logging
    labels:
      reproxy.server: 'echo.umputun.com'
      reproxy.route: '^/(.*)'

  updater:
    image: ghcr.io/umputun/updater:master
    container_name: "updater"
    hostname: "updater"
    restart: always
    logging: *default_logging
    environment:
      - LISTEN=0.0.0.0:8080
      - KEY=super-secret-password
      - CONF=/srv/etc/updater.yml
    ports:
      - "8080"
    volumes:
      - ./etc:/srv/etc
      - /var/run/docker.sock:/var/run/docker.sock
    labels:
      reproxy.server: 'jess.umputun.com'
      reproxy.route: '^/(.*)'

Working with docker-compose

For a simple container, started with all the parameters manually, the typical update sequence can be as simple as "kill container and recreate it", however docker compose-based container can be a little trickier. If user runs updater directly on the host (not from a container) the update command can be as trivial as "docker-compose pull && docker-compose up -d ". In case if updater runs from a container the simplest way to do the same is "ssh user@bridge-ip docker-compose ...". To simplify the process the openssh-client already preinstalled.

This is an example of ssh-based updater.yml

tasks:

  - name: remark42-site
    command: |
      echo "update remark42-site with compose"
      ssh [email protected] "cd /srv && docker-compose pull remark42-site && docker-compose up -d remark42-site"

  - name: reproxy-site
    command: |
      echo "update reproxy-site"
      ssh [email protected] "cd /srv && docker-compose pull reproxy-site && docker-compose up -d reproxy-site"

Creating user for SSH connection from updater

# updater container uses user app so it would be convinient to connect using the same name
sudo useradd -m -d /home/app -s /bin/bash app
sudo usermod -a -G docker app
sudo su - app
ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_rsa -C updater
mv .ssh/id_rsa.pub .ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
# proper user and group for private key to be used inside the container
chown 1001:1001 ~/.ssh/id_rsa
logout
# then attach /home/app/.ssh/id_rsa to a /home/app/.ssh/id_rsa on the container where updater runs if necessary

Other use cases

The main goal of this utility is to update containers; however, all it does is the remote activation of predefined commands. Such command can do anything user like, not just "docker pull && docker restart." For instance, it can be used to schedule remote jobs from some central orchestrator, run remote cleanup jobs, etc.

All parameters

  -f, --file=         config file (default: updater.yml) [$CONF]
  -l, --listen=       listen on host:port (default: localhost:8080) [$LISTEN]
  -k, --key=          secret key [$KEY]
  -b, --batch         batch mode for multi-line scripts
      --limit=        limit how many concurrent update can be running (default: 10)
      --timeout=      for how long update task can be running (default: 1m)
      --update-delay= delay between updates (default: 1s)
      --dbg           show debug info [$DEBUG]

Help Options:
  -h, --help    Show this help message