library images on steroids

doc

• Idea is to inject some tools inside base library images

• We do not wrap ONBUILD based images.

• For all we want:

  • the network swissknifes: socat, netcat, curl, wget.
  • cops_pkgmgr_install.sh: arch agnostic package installer
  • setup_locales.sh: helper to build and setup the default locale
  • openssl: The SSL toolkit.
  • cron: isc cron on debian like, cronie on redhat, busybox cron on alpine (dcron).
  • rsyslog: the system logger
  • logrotate: the venerable but still useful versatile logrotator
  • bash: the venerable shell
  • ca certificates: bundle of ROOT cas for SSL connections.
  • process supervisors:
    • forego: foreman in go, supervisord/runit/circus/foreman alike
    • supervisord-go: supervisord in go, attention, it has bugs like PID1 proccess reaping issues, use with care and read the tracker and specially #60!
    • runit (1)
    • monit (1)
    • foreman(ruby) & supervisord (python) are not bundled as they would add too much dependencies therefore make images grow too much.
  • frep: tool to generates configs from templates when envsubst or basic shell is just not enougth
  • confd: tool to generates configs from templates when frep is just not enougth
  • remco: tool to generates configs from templates when confd is just not enougth
  • dockerize: tool to orchestrate containers between themselves
  • gosu: tool to downgrade privileges, the perfect SUDO.
  • confenvsubst: tool to generate configs from env vars with well knows prefixes
  • p7zip: the universal (un)archiver
  • Except for alpine based images (using musl, so no locales): setup sensible locales for: fr, en, de.

• (1): if it is packaged on the underlying distrib (eg: runit is only on alpine>3)

• debian 6 (stretch) is not supported anymore (tags remain, but we wont provide active support).

• To be sure to include new tags nearly as soon as they are out, and to also refresh images to include their fixes including security patches, this repo has a Travis cron enabled to rebuild everything at least daily.

• Note: All single binaries and scripts are installed inside /cops_helpers, you can them use any docker-images related image as a source to ignite a volume or use multistage builds to copy them.

Separatly mananged images

• corpusops/postgres, corpusops/pgrouting & corpusops/postgis pipelines has been moved to this repo and those 2 children postgis-bare && pgrouring-bare images : postgis / pgrouting

repo	status
docker-images
docker-postgis
docker-pgrouting
docker-postgres

• other images managed separatly

repo	status
docker-alpine
docker-amazonlinux
docker-amazonlinux-bare
docker-archlinux
docker-centos
docker-dbsmartbackup
docker-debian
docker-docker
docker-elasticsearch
docker-gitlabtools
docker-golang
docker-mailhog
docker-mailu
docker-mariadb
docker-memcached
docker-mongo
docker-mysql
docker-nginx
docker-node
docker-opensearch
docker-pureftpd
docker-php
docker-project
docker-python
docker-rabbitmq
docker-redis
docker-redmine
docker-rsync
docker-ruby
docker-seafile
docker-slapd
docker-solr
docker-sshd
docker-tensorflow
docker-traefik
docker-ubuntu

• Those helpers (docker entrypoints) are added:

Refresh some files in this repository

• Think time to time to refresh cops_pkgmgr_install.sh comes from corpusops.bootstrap/bin

• Then run

  ./main.sh gen

• Commit the whole and check build status on travis

• Image can override any of the hooks in this order (placing a Dockerfile.<hook_name> in the image folder (precedence: tag folder itself, imagefolder (for all tags), and the default ones)

  • from
  • args
  • argspost: just a hook (empty by default)
  • helpers
  • pre: just a hook (empty by default)
  • base
  • post: just a hook (empty by default)
  • clean
  • cleanpost: just a hook (empty by default)

Zoom on entryoints

You better have to read the entrypoints to understand how they work.

supervisord helper: /bin/supervisord.sh

• /bin/supervisord.sh: helper to dockerize supervisord-go

  • generates its config (read the helper) by concatenating all config (.conf, .ini) files found inside subdirectories of
    /etc/supervisor.d($SUPERVISORD_CONFIGS_DIR), /etc/supervisor, /etc/supervisord.
  • frep is done on config files for all vars beginning by SUPERVISORD_
  • SUPERVISORD_CONFIGS can be set to alternate configs to aggregate to supervisord config, if the file is with a relative path, it will be searched inside /etc/supervisor.d
  • SUPERVISORD_LOGFILE can be set up to another path, as we set it to stdout by defaut

• One usual way to use this providen entrypoint is to launch it through supervisor to gain also logrotate support for free.
  

  # configs can be given on CLI, v2
  supervisord:
    image: "corpusops/supervisord"
    command:  /bin/supervisord.sh s.conf
  # configs can be given on CLI, v1
  supervisord:
    image: "corpusops/supervisord"
    entrypoint: /bin/supervisord.sh
    command: [s.conf]
  # /etc/supervisor.d/s.conf is a valid supervisord config snippet
  supervisord:
    image: "corpusops/supervisord"
    entrypoint: /bin/supervisord.sh
    environment:
    - SUPERVISORD_CONFIGS=s.conf
  # /foo/s.conf is a valid supervisord config snippet
  supervisord:
    image: "corpusops/supervisord"
    entrypoint: /bin/supervisord.sh
    environment:
    - SUPERVISORD_CONFIGS=/foo/s.conf

forego helper: /bin/forego.sh

• /bin/forego.sh: helper to dockerize forego :

  • envsubst is done on Procfiles for all vars beginning by FOREGO_

• As you may know, forego uses a Procfile to configure itself.

  • You can either use this entrypoint directly by giving args including the Procfile

  • Or, easier, you can use The PROCFILE env var pointing to your config.

    • This config file will be parsed by envsubst.

  nginx:
    command: "corpusops/nginx"
    entrypoint: /bin/forego.sh -d /my/path
    environment:
    # This way your procfile can be processed by envsubst !
    - FOREGO_PROCFILE=/my/path/.Procfile

cron helper: /bin/cron.sh

• /bin/cron.sh: helper to dockerize cron
• When you use a debian/ubuntu based image, it's impossible to use cron base logging as it is based on syslog.
  
  • see this bug
• When you use other implementation, you can redirect to a file, but it won't end up into docker logs.
• So we made an entrypoint
  • 1. to handle different implementation startup arguments
  • 2. to handle a named pipe to escalate cron logs up to docker logs instead of a regular log file.
• What you have to do to log is to redirect output to /var/log/cron.log.

  • Usage is as easy as putting this in your docker-compose file

  • ALT: (not recommanded) without supervisor:

    ---
    version: "3.6"
    services:
      # for alpine
      alpinecron:
        image: corpusops/alpine-bare
        command:
        - /bin/sh
        - "-c"
        - >-
          frep /mycrontab.frep:/etc/crontabs/mycrontab --overwrite
          && chmod 0700 /etc/crontabs/mycrontab
          && exec /bin/supervisord.sh
        environment:
        - SUPERVISORD_CONFIGS=/etc/supervisor.d/cron /etc/supervisor.d/rsyslog
        volumes:
        - ./mycrontab:/mycrontab.frep
        - ../rootfs/etc/rsyslog.conf.frep:/etc/rsyslog.conf.frep
      # for debian/redhat alike
      ubuntucron:
        image: corpusops/ubuntu-bare
        command:
        - /bin/sh
        - "-c"
        - >-
          frep /mycrontab.frep:/etc/cron.d/mycrontab --overwrite
          && chmod 0700 /etc/cron.d/mycrontab
          && exec /bin/supervisord.sh
        environment:
        - SUPERVISORD_CONFIGS=/etc/supervisor.d/cron /etc/supervisor.d/rsyslog
        volumes:
        - ./umycrontab:/mycrontab.frep
        - ../rootfs/etc/rsyslog.conf.frep:/etc/rsyslog.conf.frep

  • mycrontab

    # debian / ubuntu / centos: /etc/crond.d/mycrontab
    1 * * * * * root gosu myuser /bin/sh -c "backup 2>&1 | tee -a /var/log/cron.log"
    # alpine: /etc/crontabs/mycrontab
    1 * * * * * gosu myuser /bin/sh -c "backup 2>&1 | tee -a /var/log/cron.log"

nginx helper: /bin/nginx.sh

• /bin/nginx.sh: helper to dockerize nginx
• Helper image built by docker-project, tags:
  • corpusops/project:{nginx,nginx-alpine,nginx-stable,nginx-stable-alpine}
• One usual way to use this providen entrypoint is to launch it through supervisord-go to gain also logrotate support for free.
• Remember also that all files in /etc/nginx will be proccessed by frep
  
• Remember also that all files in /nginx.d if existing will be proccessed by frep with same rules and copied to /etc/nginx
  
• Also ".skip|.template" files will be skipped from processing (eg: /etc/nginx/foo.template) but you can adapt the NGINX_FREP_SKIP envvar to any regex to skip other files from frep processing
• if NO_SSL is not set, generate a self signed certificate if the certificate provided path is not already existing.
• Useful vars:
  • NGINX_FREP_SKIP=.skip|.template|.skipped: skip rendering files matching regex
  • SKIP_EXTRA_CONF=: set to 1 to skip extra conf in /nginx.d copy
  • SKIP_CONF_RENDER=: set to 1 skip frep rendering
  • SKIP_OPENSSL_INSTALL=: set to 1 skip openssl autoinstall if not installed
  • ALL XXX_HTTP_PROTECT_USER/XXX_HTTP_PROTECT_PASSWORD/XXX_HTTP_PROTECT_FILE: generate $XXX_HTTP_PROTECT_FILE & /etc/htpasswd/protect htpasswd files with those credentials
    • if $XXX_HTTP_PROTECT_FILE isnt set, it defaults to /etc/htpasswd/xxxprotect
    • if $XXX_HTTP_PROTECT_USER isnt set, it defaults to root
    • /etc/htpasswd/protect will contain all defined users
    • Symlinks from /etc/htpasswd-xxxprotect are done for convenience (retrocompat)
  • VHOST_TEMPLATES: list of vhost template to render through frep. (default: /etc/nginx/conf.d/default.conf)
  • VHOST_TEMPLATE_EXTS: exts to search for templates
  • NO_SSL=1: set to 1 not to generate a selfisgned certificate for SSL_CERT_BASENAME and SSL_ALT_NAMES (space sparated)
  • SSL_CERT_PATH=/certs/cert.pem: ssl certificate path (also used when using the selfsigned certificate generator)
  • SSL_KEY_PATH=/certs/cert.key: ssl certificate key path
• examples

  • supervisord example

    nginx:
      image: corpusops/nginx:1-alpine
      command: /bin/supervisord.sh
      environment: [SUPERVISORD_CONFIGS=cron nginx rsyslog]
      volumes:
      - ./nginx:/nginx.d
    

  • supervisord custom example

    nginx:
      image: corpusops/nginx:1-alpine
      command: >
        /bin/sh -exc "
        frep /etc/nginx/conf.d/default.conf.template:/etc/nginx/conf.d/default.conf --overwrite
        && exec /bin/supervisord.sh"
      environment: [SUPERVISORD_CONFIGS=cron nginx rsyslog]
      volumes:
      - ./myvhost.conf:/etc/nginx/conf.d/default.conf.template
    

CopsHelpers installer: /bin/install_cops_helpers.sh

• Helper image built by docker-project, tags:
  • corpusops/project:helpers-ubuntu
  • corpusops/project:helpers-ubuntu-{22,20,16,14,16}.04
  • corpusops/project:helpers-debian
  • corpusops/project:helpers-debian-{11,10,9,8}
  • corpusops/project:helpers-alpine
  • corpusops/project:helpers-alpine{3}
  • corpusops/project:helpers-centos
  • corpusops/project:helpers-centos-{9,8,7}
  • corpusops/project:helpers-centos-stream
  • corpusops/project:helpers-centos-stream{9,8,7}
• Install all helpers from /cops_helpers to $HELPERS_DIR (/helpers)
• It will start a dummy http server to work in pair with sidekar containers which use dockerize, unless you set SKIP_HELPERS_SERVICE=1, eg

helpers:
  image: corpusops/project:helpers-ubuntu-22.04
  volumes: [helpers:/helpers]
redmine:
  volumes: [helpers:/helpers]
  entrypoint:
  - /bin/bash
  - '-exc'
  - |-
    export PATH="/helpers:$PATH";until [ -e /helpers/frep ];do sleep 1;done;dockerize -wait http://helpers -timeout 120s
    # now frep is available
    frep /conf/foo:/conf/bar --overwrite
    /start

SSL Certificate Helper: /bin/cops_gen_cert.sh

• see script

• controlled via env vars:

  SSL_COMMON_NAME=  # default: $hostname
  SSL_ALT_NAMES=  # default: $hostname www.$hostname
  SSL_CERT_BASENAME=  # default to hostname and "cert" through nginx script
  SSL_CERT_PATH=
  SSL_KEY_PATH=
  SSL_KEY_VALIDITY=  # cert validity in days
  SSL_CERT_VALIDITY=  # cert validity in days
  SSL_DIR_MODuE=  # directory perms mode
  SSL_CERT_MODE=  # cert perms mode
  SSL_KEY_MODE=  # key perms mode
  SSL_CERT=  # x509 cert value if you want to give it
  SSL_KEY=   # x509 cert key value if you want to give it

• If SSL_CERT is empty, a SSL key will be generated

• If SSL_KEY is empty, a selfsigned cert will be generated

traefik helper: /bin/traefik.sh

• /bin/traefik.sh: helper to dockerize traefik
• As you may know, forego uses a Procfile to configure itself.

  • You can either use this entrypoint directly by giving args including the traefik config

  • Or, easier, you can use either

    • the TRAEFIK_CONFIG env var pointing to your config.
    • mount a file to /traefik.toml

  • This config file will be parsed by envsubst for any env var prefixed by TRAEFIK_.

    traefik:
      image: "corpusops/traefik"
      entrypoint: /bin/traefik.sh
      environment:
      # if this file exists, it will be used as the config automatically
      - TRAEFIK_CONFIG=/traefik.toml

Use rsyslog image

• See ./corpusops/rsyslog.
• tag is corpusops/rsyslog
  • OS based variants:
    • corpusops/rsyslog:{debian,alpîne,ubuntu}
• this image exposes a syslog daemon on port 10514
• It will split with its default config every log inside /var/log/docker/<prog_name>.log
• logs also go to stdout
• env vars (mainly to control log retention) [see logrotate]:
  • RSYSLOG_PORT=10514: rsyslog port
  • LOGROTATE_SIZE=5M: size to trigger a logrotate from.
  • LOGROTATE_DAYS=30: number of days to keep logs for.
  • LOGROTATE_LONGRETENTION_DAYS=365: number of days to keep long retention (web & loadbalancers) logs for.
  • RSYSLOG_DOCKER_LOGS_PATH=/var/log/docker: path to logs
  • RSYSLOG_DOCKER_LONGRETENTION_LOGS_PATH=/var/log/docker/longretention: path to logs with long retention
  • RSYSLOG_DOCKER_LONGRETENTION_PATTERN=^(lb|nginx|proxy|traefik|haproxy|apache): regex to know which tagnames can be treated as long retention logs
  • RSYSLOG_SPLITTED_CONFIGS=1:
    • if 1: logs are splitted under /var/log/docker/<prog_name>.log
    • else things go inside like usually in /var/log
• Any file inside /entry will be copied to /etc with same location
• Any file named *.frep into /etc/logrotate.d && /etc/rsyslog.d will be processed through frep

One current pattern is to redirect docker logs through a local syslog this way:

x-vars:
  base: &base
    restart: always
    # this will configure the baremetal host to reroute logs
    # through localhost:1514 which forwards to ``log`` container itself
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://localhost:1514"
        tag: "someservice"
services:
  log:
    <<: [ *base ]
    image: corpuspops/rsyslog
    ports: ["127.0.0.1:1514:10514"]
    # ensure no syslog log loop
    logging: {driver: "json-file", options: {max-size: "10M", max-file: "50"}}
  someservice:
    <<: [ *base ]
    image: some/service

mailhog helper: /bin/project_mailhog.sh

• Helper image built by docker-project, tags:

  • corpusops/project:mailhog

• corpusops/project:mailhog: mailhog wrapper to setup a user/password file from envvars:

  • MAILCATCHER_PASSWORD
  • MAILCATCHER_USER

• smtp_port is on port 1025, UI/API on port 8025

  mailcatcher:
    image: "corpusops/project:mailhog"
    hostname: mailcatcher
    volumes: ["mails:/mails"]

dbsetup : /bin/project_db_setup.sh

• Helper image built by docker-project, tags:
  • corpusops/project:dbsetup
• helper to wait for db availability and then setup a dummy webserver to help dependent services orchestration