doc/Container.md

   1 # [ngIRCd](https://ngircd.barton.de) - Container How-To
   2
   3 The ngIRCd daemon can be run as a containerized application, for example using
   4 Docker or Podman (the latter being preferred and used in the examples below).
   5 The container definition file, also known as "Docker file", is bundled with this
   6 distribution as `contrib/Dockerfile` and based on the official "stable-slim"
   7 container of the Debian project (see https://hub.docker.com/_/debian).
   8
   9 ## Building the container
  10
  11 You can use the following command to build the ngIRCd container image:
  12
  13 ```bash
  14 podman build --format=docker -f contrib/Dockerfile .
  15 ```
  16
  17 The `Dockerfile` includes a `HEALTHCHECK` directive, which is not supported by
  18 the default OCI 1.0 image format, therefore we use the "docker" format here.
  19
  20 If you are using Git, you can tag the built image like this (use the ID of the
  21 newly built image!):
  22
  23 ```bash
  24 podman tag <container_id> "ngircd:$(git describe --tags | sed 's/rel-//g')"
  25 ```
  26
  27 ## Running the container
  28
  29 You can use this command to run the ngIRCd container using Podman, for example:
  30
  31 ```bash
  32 podman run --name=ngircd --detach \
  33   -p 127.0.0.1:6667:6667 \
  34   ngircd:<tag>
  35 ```
  36
  37 This creates and starts a new container named "ngircd" from the image
  38 "ngircd:<tag>" (you habe to substitute _<tag>_ with the real tag name here!) and
  39 maps the host port 6667 on localhost to the port 6667 inside of the container.
  40
  41 ### Configuring the container
  42
  43 The ngIRCd inside of the container is installed inside of `/opt/ngircd/` and the
  44 default drop-in directory is `/opt/ngircd/etc/ngircd.conf.d`. Therefore you can
  45 map a host folder to this drop-in directory inside of the container and place
  46 drop-in configuration file(s) in the host path like this:
  47
  48 ```bash
  49 mkdir -p /host/path/to/ngircd/conf.d
  50 touch /host/path/to/ngircd/conf.d/my.conf
  51 podman run --name=ngircd --detach \
  52   -p 127.0.0.1:6667:6667 \
  53   -v /host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d' \
  54   ngircd:<tag>
  55 ```
  56
  57 ### Testing the configuration
  58
  59 As with the native daemon, it is a very good idea to validate the configuration
  60 of the daemon after making changes.
  61
  62 With Docker and Podman, you can pass arguments to the `ngircd` binary inside of
  63 the container by simply appending it to the "run" command line like this:
  64
  65 ```bash
  66 podman run --name=ngircd --rm -it \
  67   -v /host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d' \
  68   ngircd:<tag>
  69   --configtest
  70 ```
  71
  72 ### Reloading the daemon configuration in a running container
  73
  74 To activate changed configuration of ngIRCd, you can either restart the
  75 container (which will disconnect all currently connected clients) or signal
  76 `ngircd`(8) inside of the running container to reload its configuration file(s).
  77
  78 The latter can be done with this command, for example:
  79
  80 ```bash
  81 podman exec -it ngircd /bin/bash -c 'kill -HUP $(/usr/bin/pidof -s ngircd)'
  82 ```