Skip to content

alpine-kanboard

updated stars forks watchers issues issues-pr
pulls stars aarch64 armhf armv7l i386 ppc64le riscv64 s390x x86_64

MultiArch Alpine Linux + S6 + NGINX + PHP-fpm + Kanboard

This image containerizes Kanboard kanban webapp and the background worker using Beanstalk along with its php dependencies to track tasks for an individual or small group.

Based on Alpine Linux (v3.22) from the php image with NGINX, PHP and the kanboard scripts overlayed on it. Versioned accordingly with releases from /kanboard/kanboard.

Get the Image

Pull the image from Docker Hub.

docker pull woahbase/alpine-kanboard
Image Tags

The image is tagged respectively for the following architectures,

latest tag is annotated as multiarch so pulling without specifying any architecture tags should fetch the correct image for your architecture. Same goes for any of the version tags.

non-x86_64 images used to contain the embedded qemu-user-static binary which has been redundant for a while, and is being deprecated starting with our Alpine Linux v3.22 base-image release, see qemu-user-static or the more recent binfmt instead for running multi-arch containers.

Run

Running the container starts the service.

docker run --rm \
  --name docker_kanboard \
  -e KANBOARD_URL="http://localhost/kanboard/" \
  -p 443:443 \
  -p 80:80 \
  -v $PWD/data:/config/www/kanboard/data \
  -v $PWD/plugins:/config/www/kanboard/plugins \
woahbase/alpine-kanboard
Multi-Arch Support

If you want to run images built for other architectures on the same host (e.g. a x86_64 machine), you will need to have the specific binary format support configured on your host machine before running the image (otherwise you get an exec format error). Here's how,

For recent images, we can use tonistiigi's binfmt image to register binary execution support for the target architecture, like the following,

docker run --rm --privileged tonistiigi/binfmt --install <architecture>

Architecture is that of the image we're trying to run, can be arm64 for aarch64, arm for both armv7l and armhf, or amd64 for x86_64. See binfmt.

Previously, multiarch, had made it easy for us by packing qemu into an image, so we could just run

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

However, that image (see qemu-user-static) seems to have fallen behind in updates, and with newer images the binfmt method is preferable.

Now images built for other architectures will also be executable. This is optional though, without the above, you can still run the image that is specifically made to support your host architecture.

Configuration

We can customize the runtime behaviour of the container with the following environment variables.

ENV Vars Default Description
KANBOARDDIR /config/www/kanboard (Preset) Path to Kanboard installation.
KANBOARD_URL http://localhost/kanboard/ FQDN of your kanboard host including subpath, (kanboard is available at path /kanboard/). Required to set the first-run URL in database. (Relevant issue)
KANBOARD_BACKUPDIR /config/www Path to directory where current installation backup is generated during an update.
KANBOARD_UPDATE unset If set to true, will reinstall kanboard at ${KANBOARDDIR} even if a previous installation exists. Useful if you're persisting your whole installation. Also generates a backup of the previous installation at ${KANBOARD_BACKUPDIR}/kanboard-VERSION-YYYY-MM-DD.zip
KANBOARD_PRESERVEFILES data,plugins,config.php Comma-separated list of files/dirs that are excluded from deletion during an update.
KANBOARD_CRONFILE /etc/crontabs/root Cron-registry file of a user (defaults to root). This file is modified to contain the periodic task script that will be executed.
KANBOARD_CRONJOB /defaults/cronjob.sh File to execute on cron invocation.
KANBOARD_CRONTIME 0 8 * * * cron-formatted invocation timings.
PHPDIR /etc/php82 Root directory for php config files.
PHPCONFDIR /etc/php82/conf.d Directory for php config snippets.
PHP_MAX_EXECUTION_TIME 30 php.ini value for max_execution_time. (Only set if file does not exist)
PHP_MAX_FILE_UPLOADS 20 php.ini value for max_file_uploads. (Only set if file does not exist)
PHP_MEMORY_LIMIT 128M php.ini value for memory_limit. (Only set if file does not exist)
PHP_POST_MAX_SIZE 16M php.ini value for post_max_size. (Only set if file does not exist)
PHP_UPLOAD_MAX_FILESIZE 16M php.ini value for upload_max_filesize. (Only set if file does not exist)
PHP_OPCACHE_ENABLE_CLI 0 php.ini value for opcache.enable_cli. (Only set if file does not exist.) (since 8.2.22)
PHP_SKIP_PERMFIX unset If set to a non-empty-string value (e.g. 1), skips fixing permissions for php configuration files/directories. (since 8.2.27)
PHP_ADD_DEFAULT_PHPINFO unset If set to true and no php scripts exist inside ${WEBDIR}, a default phpinfo.php is copied into it. Useful for testing. (since 8.2.22) Previously PHP_SKIP_DEFAULT_PHPINFO, enabled by default.
PHP_PERMFIX_WEBDIR unset If set to true, ensures files inside ${WEBDIR} are owned/accessible by ${S6_USER}. (since 8.2.22)
PHPFPMCONF /etc/php82/php-fpm.conf php-fpm main config file.
PHPFPMDIR /etc/php82/php-fpm.d Directory for php-fpm config snippets.
PHPFPMSOCK /var/run/php-fpm.sock php-fpm socket file location.
PHPFPM_ARGS -F Customizable arguments passed to php-fpm service at runtime.
PHPFPM_ERROR_LOG /proc/self/fd/2 php-fpm.conf value for error_log. (Only set if file does not exist)
PHPFPM_LOG_LEVEL error php-fpm.conf value for log_level. (Only set if file does not exist) (since 8.2.22)
PHPFPM_CATCH_WORKERS_OUTPUT no php-fpm.d/www.conf value for catch_workers_output. (Only set if file does not exist) (since 8.2.22)
PHPFPM_CLEAR_ENV yes php-fpm.d/www.conf value for clear_env. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM dynamic php-fpm.d/www.conf value for pm. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM_MAX_CHILDREN 5 php-fpm.d/www.conf value for pm.max_children. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM_MAX_REQUESTS 500 php-fpm.d/www.conf value for pm.max_requests. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM_MAX_SPARE_SERVERS 3 php-fpm.d/www.conf value for pm.max_spare_servers. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM_MIN_SPARE_SERVERS 1 php-fpm.d/www.conf value for pm.min_spare_servers. (Only set if file does not exist) (since 8.2.22)
PHPFPM_PM_START_SERVERS 2 php-fpm.d/www.conf value for pm.start_servers. (Only set if file does not exist) (since 8.2.22)
ROOTDIR /config Root directory for nginx configs or webserver files.
NGINXDIR /config/nginx Default directory for nginx configurations.
CONFSDIR /config/nginx/conf.d For shared configuration snippets.
LOGSDIR /config/nginx/logs For logs (especially if run as a non-root user). (since 1.28.0)
SITESDIR /config/nginx/http.d For webserver host configuration files.
STREAMSDIR /config/nginx/stream.d For stream configuration files. (Optional, requires stream module to be enabled in configurations).
TMPDIR /config/nginx/tmp For temporary or buffer files e.g. client body, cgi or proxy caches (especially if run as a non-root user). (since 1.28.0)
NGINX_NO_HTTP unset Set to 'true' to disable default http(80) conf file, has no effect if custom site-confs exist.
NGINX_NO_HTTPS unset Set to 'true' to disable default https(443) conf file, and default self-signed certificate generation on first run.
KEYDIR /config/keys Default certificate/privatekey location.
PKEYFILE /config/keys/private.key Default path to privatekey. (Make sure site-confs reflect the same)
CERTFILE /config/keys/certificate.crt Default path to certificate. (Make sure site-confs reflect the same)
SSLSUBJECT see here Default SSL Subject for self-signed certificate generation on first run.
NGINX_NO_CERTGEN unset Set to 'true' to disable default self-signed certificate generation on first run.
HTPASSWDFILE /config/keys/.htpasswd Default path to .htpasswd. (Make sure site-confs reflect the same)
WEBADMIN admin Default admin user in .htpasswd. (Not changed if file already exists)
PASSWORD insecurebydefault Default admin user password in .htpasswd.
NGINX_NO_HTPASSWD unset Set to 'true' to disable default htpasswd generation on first run.
NGINX_SKIP_FASTCGI_PARAM unset If set to true, skip appending custom fastcgi_param configuration. (since 1.26.2)
NGINX_FASTCGI_PARAMSFILE /etc/nginx/fastcgi_params Customizable fastcgi_param filepath. (since 1.26.2_20250225)
WEBDIR /config/www For serving files, e.g. either static HTML or dynamic scripts i.e. with PHP.
NGINX_ADD_DEFAULT_INDEX unset If set to true and no files exist inside ${WEBDIR}, a static index.html is copied into it. Useful for testing. (since 1.26.2) Previously NGINX_SKIP_DEFAULT_INDEX, enabled by default.
NGINX_SKIP_PERMFIX unset If set to a non-empty-string value (e.g. 1), skips fixing permissions for nginx configuration files/directories. (since 1.26.2_20250225)
NGINX_PERMFIX_WEBDIR unset If set to true, ensures files inside ${WEBDIR} are owned/accessible by ${S6_USER}. (since 1.26.2)
NGINX_ARGS -F Customizable arguments passed to nginx service at runtime. (since 1.28.0)
CROND_ARGS -f -S -l 5 Customizable arguments passed to cron daemon.
CROND_CONF /etc/crontabs Default file to read configurations from. By default this file enables scripts from /etc/periodic to be executed.
SKIP_CRON unset Set to true to skip starting cron daemon.
S6_NEEDED_PACKAGES empty string Space-separated list of extra APK packages to install on start. E.g. "curl git tzdata"
PUID 1000 Id of ${S6_USER}.
PGID 1000 Group id of ${S6_USER}.
S6_USER alpine (Preset) Default non-root user for services to drop privileges to.
S6_USERHOME /home/alpine (Preset) HOME directory for ${S6_USER}.
Did you know?

You can check your own UID/GID by running the command id in a terminal.

Also,

  • By itself, only SQLITE Database storage included. Checkout alpine-mysql or alpine-postgresql to configure your own database server as another container.

  • Kanboard is located at the endpoint /kanboard/, with the webapp at /config/www/kanboard/. If not exists, (or if KANBOARD_UPDATE is set) the release included in the image gets unzipped at this path.

  • Configuration file is at /config/www/kanboard/config.php, edit or remount this with your own. A sample is provided in /defaults, this gets copied when no such file exists before service is started.

  • You can either mount only the data and plugins directories to persist between updates, or mount the whole /config directory to have better (but manual) control over your installation.

  • For first-time-right setups provide correct KANBOARD_URL to be set in the database. (Relevant issue)

  • Kanboard source is located at /opt/kanboard/kanboard-${VERSION}.zip.

  • Includes Beanstalk and the supporting plugin.

  • 8-hourly cronjob is enabled by default.

  • Includes everything from the alpine-php image.

  • Which in turn, includes everything from the alpine-nginx image.

  • Which in turn, includes everything from the alpine-s6 image.

Stop the container with a timeout, (defaults to 2 seconds)

docker stop -t 2 docker_kanboard

Restart the container with

docker restart docker_kanboard

Removes the container, (always better to stop it first and -f only when needed most)

docker rm -f docker_kanboard
Shell access

Get a shell inside a already running container,

docker exec -it docker_kanboard /bin/bash

Optionally, login as a non-root user, (default is alpine)

docker exec -u alpine -it docker_kanboard /bin/bash

Or set user/group id e.g 1000/1000,

docker exec -u 1000:1000 -it docker_kanboard /bin/bash
Logs

To check logs of a running container in real time

docker logs -f docker_kanboard
As-A-Service

Run the container as a service with the following as reference (and modify it as needed).

With docker-compose (alpine-kanboard.yml)

---
services:
  kanboard:
    container_name: kanboard
    # depends_on:
    #   mysql:
    #     condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: '2.00'
          memory: 1024M
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 5
        window: 120s
    environment:
      # KANBOARD_URL: "http://your-domain.local/kanboard/"
      # KANBOARD_UPDATE: "false"
      PUID: ${PUID:-1000}
      PGID: ${PGID:-1000}
      # TZ: ${TZ}
    # healthcheck:
    #   interval: 2m
    #   retries: 5
    #   start_period: 5m
    #   test:
    #     - CMD-SHELL
    #     - >
    #       wget --quiet --tries=1 --no-check-certificate --spider "http://localhost:80/kanboard/" || exit 1
    #   timeout: 10s
    hostname: kanboard
    image: woahbase/alpine-kanboard:${KANBOARD_TAG:-latest}
    network_mode: bridge
    ports:
      - protocol: tcp
        host_ip: 0.0.0.0
        published: ${KANBOARD_PORT:-80}
        target: 80
      # # optionally with https
      # # requires certificates, either provided, or self-signed ones generated
      # - protocol: tcp
      #   host_ip: 0.0.0.0
      #   published: ${KANBOARD_HTTPS_PORT:-443}
      #   target: 443
    volumes:
      # - type: bind  # to use your own certificates with kanboard
      #   source: ${CERTIFICATE_DIR:?err}
      #   target: /config/keys
      #   bind:
      #     create_host_path: true
      # - type: bind
      #   source: ${KANBOARD_DIR:?err}/config/log
      #   target: /config/log
      #   bind:
      #     create_host_path: true
      - type: bind
        source: ${KANBOARD_DIR:?err}/data
        target: /config/www/kanboard/data
        bind:
          create_host_path: true
      - type: bind
        source: ${KANBOARD_DIR:?err}/plugins
        target: /config/www/kanboard/plugins
        bind:
          create_host_path: true
      # - type: bind
      #   source: ${KANBOARD_DIR:?err}/config.php
      #   target: /config/www/kanboard/config.php
      #   bind:
      #     create_host_path: false
      - type: bind
        source: /etc/localtime
        target: /etc/localtime
        read_only: true
        bind:
          create_host_path: false

With HashiCorp Nomad (alpine-kanboard.hcl)

variables {
  dc   = "dc1" # to load the dc-local config file
  pgid = 1000  # gid for docker
  puid = 1000  # uid for docker
  version = "1.2.40"
}
# locals { var = yamldecode(file("${var.dc}.vars.yml")) } # load dc-local config file

job "kanboard" {
  datacenters = [var.dc]
  # namespace   = local.var.namespace
  # priority    = 50
  # region      = local.var.region
  type        = "service"

  constraint { distinct_hosts = true }

  # vault { policies = ["nomad-kv-readonly"] }

  group "docker" {
    count = 1

    restart {
      attempts = 2
      interval = "2m"
      delay    = "15s"
      mode     = "fail"
    }
    update {
      max_parallel     = 1
      min_healthy_time = "10s"
      healthy_deadline = "3m"
      auto_revert      = false
    }

    service {
      name        = NOMAD_JOB_NAME
      port        = "http"
      tags        = ["ins${NOMAD_ALLOC_INDEX}", attr.unique.hostname, "urlprefix-/kanboard"]
      canary_tags = ["canary${NOMAD_ALLOC_INDEX}", "urlprefix-/c/kanboard"]
      check {
        name      = "${NOMAD_JOB_NAME}@${attr.unique.hostname}:${NOMAD_HOST_PORT_http}=>${NOMAD_PORT_http}"
        type      = "tcp"
        # path      = "/kanboard"
        interval  = "60s"
        timeout   = "10s"
      }
      check_restart {
        limit     = 3
        grace     = "10s"
      }
    }

    ephemeral_disk { size = 128 } # MB
    network {
      # dns { servers = local.var.dns_servers }
      port "http" {
        static = 64806
        to     = 80
      }
      # port "https" {
      #   static = 63806
      #   to     = 443
      # }
    }
    volume "nomad-kanboard-data" {
      type      = "host"
      read_only = false
      source    = "nomad-kanboard-data"
    }
    volume "nomad-kanboard-plugins" {
      type      = "host"
      read_only = false
      source    = "nomad-kanboard-plugins"
    }

    task "kanboard" {
      driver = "docker"

      config {
        healthchecks { disable = true }
        hostname     = NOMAD_JOB_NAME
        image        = "woahbase/alpine-kanboard:${var.version}"
        network_mode = "bridge"
        ports        = ["http"]

        logging {
          type = "journald"
          config {
            mode = "non-blocking"
            tag = NOMAD_JOB_NAME
          }
        }

        # mount {
        #   source   = "local/config.php"
        #   target   = "/config/www/kanboard/config.php"
        #   type     = "bind"
        #   readonly = true
        # }

        # mount {
        #   source   = "local/nginx.conf"
        #   target   = "/config/nginx/http.d/http"
        #   type     = "bind"
        #   readonly = true
        # }

        # mount {
        #   source   = "secrets/keys"
        #   target   = "/config/keys"
        #   type     = "bind"
        #   readonly = false
        # }

        mount {
          type     = "bind"
          target   = "/etc/localtime"
          source   = "/etc/localtime"
          readonly = true
        }
      }

      volume_mount {
        # ensure policies allow vault-generated-token to read-write to the volume
        volume      = "nomad-kanboard-data"
        destination = "/config/www/kanboard/data"
        read_only   = false
      }
      volume_mount {
        volume      = "nomad-kanboard-plugins"
        destination = "/config/www/kanboard/plugins"
        read_only   = false
      }

      env {
        # KANBOARD_URL = "http://kanboard.service.consul/kanboard/"
        # KANBOARD_UPDATE = "false"

        # NGINX_NO_HTTPS = "true"
        # NGINX_NO_CERTGEN = "true"
        # NGINX_NO_HTPASSWD = "true"

        PGID = var.pgid
        PUID = var.puid

        # TZ   = local.var.tz
      }

      resources {
        cpu    = 512 # MHz
        memory = 512 # MB
      }

      # template {
      #   destination   = "secrets/keys/certificate.crt"
      #   data          = <<-EOP
      #     {{ with secret "kv/data/nomad/${var.dc}/certificates/selfsigned" -}}
      #     {{   index .Data.data "certificate.crt"}}
      #     {{- end }}
      #   EOP
      #   change_mode   = "restart"
      #   perms         = "444"
      #   error_on_missing_key = true
      # }

      # template {
      #   destination   = "secrets/keys/private.key"
      #   data          = <<-EOP
      #     {{ with secret "kv/data/nomad/${var.dc}/certificates/selfsigned" -}}
      #     {{   index .Data.data "private.key"}}
      #     {{- end }}
      #   EOP
      #   change_mode   = "restart"
      #   perms         = "444"
      #   error_on_missing_key = true
      # }

      # template {
      #   destination = "local/config.php"
      #   data        = <<-EOC
      #     {{ key "nomad/${var.dc}/kanboard/config.php" }}
      #   EOC
      #   change_mode = "restart"
      #   perms       = "755"
      #   error_on_missing_key = true
      # }

      # template {
      #   destination = "local/nginx.conf"
      #   data        = <<-EOC
      #     {{ key "nomad/${var.dc}/kanboard/nginx" }}
      #   EOC
      #   change_mode = "restart"
      #   perms       = "644"
      #   error_on_missing_key = true
      # }
    }

    # task "await-service-mysql" {
    #   driver = "raw_exec"
    #   # user   = local.var.exec_user
    #
    #   config {
    #     command = "bash"
    #     args    = [ "-c", <<-EOS
    #       echo -n Waiting for $SVC_MYSQL.; \
    #       until \
    #         drill $SVC_MYSQL 2>/dev/null | grep -q 'rcode: NOERROR'; \
    #         do echo -n ' .'; sleep $WAIT_SEC; done; \
    #       echo 'Available.'; \
    #     EOS
    #     ]
    #   }
    #
    #   env {
    #     SVC_MYSQL = "mysql.service.${var.dc}.consul"
    #     WAIT_SEC  = 10
    #   }
    #
    #   lifecycle {
    #     hook    = "prestart"
    #     sidecar = false
    #   }
    # }
  }
}
Reverse Proxy

To proxy it through a web server, see below

This snippet can be used to reverse-proxy the service using NGINX.

upstream proxy_kanboard {
    server your.host.local:<kanboard-port> fail_timeout=5;
}

## the following goes inside a server block

location /kanboard { return 301 /kanboard/; }
location /kanboard/ {
    auth_basic off;

    proxy_set_header X-Forwarded-Server $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;

    proxy_read_timeout 300;
    proxy_connect_timeout 300;
    proxy_pass http://proxy_kanboard/kanboard/;
}

Build Your Own

Feel free to clone (or fork) the repository and customize it for your own usage, build the image for yourself on your own systems, and optionally, push it to your own public (or private) repository.

Here's how...

Setting up

Before we clone the /repository, we must have Git, GNU make, and Docker (optionally, with buildx plugin for multi-platform images) setup on the machine. Also, for multi-platform annotations, we might require enabling experimental features of Docker.

Now, to get the code,

Clone the repository with,

git clone https://github.com/woahbase/alpine-kanboard
cd alpine-kanboard

To get a list of all available targets, run

make help
Always Check Before You Make!

Did you know, we could check what any make target is going to execute before we actually run them, with

make -n <targetname> <optional args>

Build and Test

To create the image for your architecture, run the build and test target with

make build test

For building an image that targets another architecture, it is required to specify the ARCH parameter when building. e.g.

make build test ARCH=aarch64 

make build test ARCH=armhf 

make build test ARCH=armv7l 

make build test ARCH=i386 

make build test ARCH=ppc64le 

make build test ARCH=riscv64 

make build test ARCH=s390x 

make build test ARCH=x86_64
Build Parameters

All images have a few common build parameters that can be customized at build time, like

  • ARCH
The target architecture to build for. Defaults to host architecture, auto-detected at build-time if not specified. Also determines if binfmt support is required before build or run and runs the regbinfmt (or inbinfmt for recent images) target automatically. Possible values could be aarch64, armhf, armv7l, or x86_64.
  • BUILDDATE
The date of the build. Can be used to create separate tags for images. (format: yyyymmdd)
  • DOCKERFILE
The dockerfile to use for build. Defaults to the file Dockerfile, but if per-arch dockerfiles exist, (e.g. for x86_64 the filename would be Dockerfile_x86_64) that is used instead.
  • TESTCMD
The command to run for testing the image after build. Runs in a bash shell.
  • VERSION
The version of the app/tool, may need to be preset before starting the build (e.g. for binaries from github releases), or extracted from the image after build (e.g. for APK or pip packages).
  • REGISTRY
The registry to push to, defaults to the Docker Hub Registry (docker.io) or any custom registry that is set via docker configurations. Does not need to be changed for local or test builds, but to override, either pass it by setting an environment variable, or with every make command.
  • ORGNAME
The organization (or user) name under which the image repositories exist, defaults to woahbase. Does not need to be changed for local or test builds, but to override, either pass it by setting an environment variable, or with every make command.

The image may also require custom parameters (like binary architecture). Before you build, check the makefile for a complete list of parameters to see what may (or may not) need to be set.

BuildX and Self-signed certificates

If you're using a private registry (a-la docker distribution server) with self-signed certificates, that fail to validate when pulling/pushing images. You will need to configure buildx to allow insecure access to the registry. This is configured via the config.toml file. A sample is provided in the repository, make sure to replace YOUR.PRIVATE.REGISTRY with your own (include port if needed).

Make to Run

Running the image creates a container and either starts a service (for service images) or provides a shell (can be either a root-shell or usershell) to execute commands in, depending on the image. We can run the image with

make run

But if we just need a root-shell in the container without any fance pre-tasks (e.g. for debug or to test something bespoke), we can run bash in the container with --entrypoint /bin/bash. This is wrapped in the makefile as

make shell
Nothing vs All vs Run vs Shell

By default, if make is run without any arguments, it calls the target all. In our case this is usually mapped to the target run (which in turn may be mapped to shell).

There may be more such targets defined as per the usage of the image. Check the makefile for more information.

Push the Image

If the build and test steps finish without any error, and we want to use the image on other machines, it is the next step push the image we built to a container image repository (like /hub), for that, run the push target with

make push

If the built image targets another architecture then it is required to specify the ARCH parameter when pushing. e.g.

make push ARCH=aarch64 

make push ARCH=armhf 

make push ARCH=armv7l 

make push ARCH=i386 

make push ARCH=ppc64le 

make push ARCH=riscv64 

make push ARCH=s390x 

make push ARCH=x86_64
Pushing Multiple Tags

With a single make push, we are actually pushing 3 tags of the same image, e.g. for x86_64 architecture, they're namely

  • alpine-kanboard:x86_64
The actual image that is built.
  • alpine-kanboard:x86_64_${version}
It is expected that the application is versioned when built or packaged, it can be specified in the tag, this makes pulling an image by tag possible. Usually this is obtained from the parameter VERSION, which by default, is set by calling a function to extract the version string from the package installed in the container, or from github releases. Can be skipped with the parameter SKIP_VERSIONTAG to a non-empty string value like 1.
  • alpine-kanboard:x86_64_${version}_${builddate}
When building multiple versions of the same image (e.g. for providing fixes or revisions), this ensures that a more recent push does not fully replace a previously pushed image. This way, although the architecture and version tags are replaced, it is possible to roll back to the previously built image by build date (format yyyymmdd). This value is obtained from the BUILDDATE parameter, and if not essential, can be skipped by setting the parameter SKIP_BUILDDATETAG to a non-empty string value like 1.
Pushing To A Private Registry

If you want to push the image to a custom registry that is not pre-configured on your system, you can set the REGISTRY variable either on the build environment, or as a makefile parameter, and that will be used instead of the default Docker Hub repository. Make sure to have push access set up before you actually push, and include port if needed. E.g.

export REGISTRY=your.private.registry:5000
make build test push

or

make build test push REGISTRY=your.private.registry:5000

Annotate Manifest(s)

For single architecture images, the above should suffice, the built image can be used in the host machine, and on other machines that have the same architecture too, i.e. after a push.

But for use-cases that need to support multiple architectures, there's a couple more things that need to be done. We need to create (or amend if already created beforehand) a manifest for the image(s) that we built, then annotate it to map the images to their respective architectures. And for our three tags created above we need to do it thrice.

Did you know?

We can inspect the manifest of any image by running 

docker manifest inspect <imagename>:<optional tag, default is latest>

Tag Latest

Assuming we built the images for all supported architectures, to facilitate pulling the correct image for the architecture, we can create/amend the latest manifest and annotate it to map the tags :aarch64, :armhf, :armv7l, :i386, :ppc64le, :riscv64, :s390x, :x86_64 to the tag :latest by running

make annotate_latest
How it works

First we create or amend the manifest with the tag latest

docker manifest create \
woahbase/alpine-kanboard:latest \
woahbase/alpine-kanboard:aarch64 \
woahbase/alpine-kanboard:armhf \
woahbase/alpine-kanboard:armv7l \
woahbase/alpine-kanboard:i386 \
woahbase/alpine-kanboard:ppc64le \
woahbase/alpine-kanboard:riscv64 \
woahbase/alpine-kanboard:s390x \
woahbase/alpine-kanboard:x86_64 \
;

docker manifest create --amend \
woahbase/alpine-kanboard:latest \
woahbase/alpine-kanboard:aarch64 \
woahbase/alpine-kanboard:armhf \
woahbase/alpine-kanboard:armv7l \
woahbase/alpine-kanboard:i386 \
woahbase/alpine-kanboard:ppc64le \
woahbase/alpine-kanboard:riscv64 \
woahbase/alpine-kanboard:s390x \
woahbase/alpine-kanboard:x86_64 \
;

Then annotate the image for each architecture in the manifest with

docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:aarch64;

docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:armhf;

docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:armv7l;

docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:i386;

docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:ppc64le;

docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:riscv64;

docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:s390x;

docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-kanboard:latest \
    woahbase/alpine-kanboard:x86_64;

And finally, push it to the repository using

docker manifest push -p woahbase/alpine-kanboard:latest
Tag Version

Next, to facilitate pulling images by version, we create/amend the image-version manifest and annotate it to map the tags :aarch64_${version}, :armhf_${version}, :armv7l_${version}, :i386_${version}, :ppc64le_${version}, :riscv64_${version}, :s390x_${version}, :x86_64_${version} to the tag :${version} by running

make annotate_version
How it works

First we create or amend the manifest with the tag ${version}

docker manifest create \
woahbase/alpine-kanboard:${version} \
woahbase/alpine-kanboard:aarch64_${version} \
woahbase/alpine-kanboard:armhf_${version} \
woahbase/alpine-kanboard:armv7l_${version} \
woahbase/alpine-kanboard:i386_${version} \
woahbase/alpine-kanboard:ppc64le_${version} \
woahbase/alpine-kanboard:riscv64_${version} \
woahbase/alpine-kanboard:s390x_${version} \
woahbase/alpine-kanboard:x86_64_${version} \
;

docker manifest create --amend \
woahbase/alpine-kanboard:${version} \
woahbase/alpine-kanboard:aarch64_${version} \
woahbase/alpine-kanboard:armhf_${version} \
woahbase/alpine-kanboard:armv7l_${version} \
woahbase/alpine-kanboard:i386_${version} \
woahbase/alpine-kanboard:ppc64le_${version} \
woahbase/alpine-kanboard:riscv64_${version} \
woahbase/alpine-kanboard:s390x_${version} \
woahbase/alpine-kanboard:x86_64_${version} \
;

Then annotate the image for each architecture in the manifest with

docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:aarch64_${version};

docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:armhf_${version};

docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:armv7l_${version};

docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:i386_${version};

docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:ppc64le_${version};

docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:riscv64_${version};

docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:s390x_${version};

docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-kanboard:${version} \
    woahbase/alpine-kanboard:x86_64_${version};

And finally, push it to the repository using

docker manifest push -p woahbase/alpine-kanboard:${version}
Tag Build-Date

Then, (optionally) we create/amend the ${version}_${builddate} manifest and annotate it to map the tags :aarch64_${version}_${builddate}, :armhf_${version}_${builddate}, :armv7l_${version}_${builddate}, :i386_${version}_${builddate}, :ppc64le_${version}_${builddate}, :riscv64_${version}_${builddate}, :s390x_${version}_${builddate}, :x86_64_${version}_${builddate} to the tag :${version}_${builddate} by running

make annotate_date
How it works

First we create or amend the manifest with the tag ${version}_${builddate}

docker manifest create \
woahbase/alpine-kanboard:${version}_${builddate} \
woahbase/alpine-kanboard:aarch64_${version}_${builddate} \
woahbase/alpine-kanboard:armhf_${version}_${builddate} \
woahbase/alpine-kanboard:armv7l_${version}_${builddate} \
woahbase/alpine-kanboard:i386_${version}_${builddate} \
woahbase/alpine-kanboard:ppc64le_${version}_${builddate} \
woahbase/alpine-kanboard:riscv64_${version}_${builddate} \
woahbase/alpine-kanboard:s390x_${version}_${builddate} \
woahbase/alpine-kanboard:x86_64_${version}_${builddate} \
;

docker manifest create --amend \
woahbase/alpine-kanboard:${version}_${builddate} \
woahbase/alpine-kanboard:aarch64_${version}_${builddate} \
woahbase/alpine-kanboard:armhf_${version}_${builddate} \
woahbase/alpine-kanboard:armv7l_${version}_${builddate} \
woahbase/alpine-kanboard:i386_${version}_${builddate} \
woahbase/alpine-kanboard:ppc64le_${version}_${builddate} \
woahbase/alpine-kanboard:riscv64_${version}_${builddate} \
woahbase/alpine-kanboard:s390x_${version}_${builddate} \
woahbase/alpine-kanboard:x86_64_${version}_${builddate} \
;

Then annotate the image for each architecture in the manifest with

docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:aarch64_${version}_${builddate};

docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:armhf_${version}_${builddate};

docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:armv7l_${version}_${builddate};

docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:i386_${version}_${builddate};

docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:ppc64le_${version}_${builddate};

docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:riscv64_${version}_${builddate};

docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:s390x_${version}_${builddate};

docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-kanboard:${version}_${builddate} \
    woahbase/alpine-kanboard:x86_64_${version}_${builddate};

And finally, push it to the repository using

docker manifest push -p woahbase/alpine-kanboard:${version}_${builddate}

That's all folks! Happy containerizing!

Maintenance

Sources at Github. Built and tested at home using Buildbot. Images at Docker Hub.

Maintained (or sometimes a lack thereof?) by WOAHBase.

Helped you save a bit of your valuable time and effort that is best spent doing stuff you actually enjoy? If you have some pocket-change to spare, kindly consider helping out.