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 tag=$(git describe --tags | sed 's/rel-//g')
  25 podman tag <container_id> "ngircd:${tag}"
  26 ```
  27
  28 ## Running the container
  29
  30 You can use this command to run the ngIRCd container using Podman, for example:
  31
  32 ```bash
  33 podman run --name=ngircd --detach \
  34   -p 127.0.0.1:6667:6667 \
  35   ngircd:<tag>
  36 ```
  37
  38 This creates and starts a new container named "ngircd" from the image
  39 "ngircd:<tag>" (you habe to substitute _<tag>_ with the real tag name here!) and
  40 maps the host port 6667 on localhost to the port 6667 inside of the container.
  41
  42 ### Configuring the container
  43
  44 The ngIRCd inside of the container is installed inside of `/opt/ngircd/` and the
  45 default drop-in directory is `/opt/ngircd/etc/ngircd.conf.d`. Therefore you can
  46 map a host folder to this drop-in directory inside of the container and place
  47 drop-in configuration file(s) in the host path like this:
  48
  49 ```bash
  50 mkdir -p /host/path/to/ngircd/conf.d
  51 touch /host/path/to/ngircd/conf.d/my.conf
  52 podman run --name=ngircd --detach \
  53   -p 127.0.0.1:6667:6667 \
  54   -v "/host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d" \
  55   ngircd:<tag>
  56 ```
  57
  58 ### Testing the configuration
  59
  60 As with the native daemon, it is a very good idea to validate the configuration
  61 of the daemon after making changes.
  62
  63 With Docker and Podman, you can pass arguments to the `ngircd` binary inside of
  64 the container by simply appending it to the "run" command line like this:
  65
  66 ```bash
  67 podman run --rm -it \
  68   -v "/host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d" \
  69   ngircd:<tag> \
  70   --configtest
  71 ```
  72
  73 ### Reloading the daemon configuration in a running container
  74
  75 To activate changed configuration of ngIRCd, you can either restart the
  76 container (which will disconnect all currently connected clients) or signal
  77 `ngircd`(8) inside of the running container to reload its configuration file(s).
  78
  79 The latter can be done with this command, for example:
  80
  81 ```bash
  82 podman exec -it ngircd /bin/bash -c 'kill -HUP $(/usr/bin/pidof -s ngircd)'
  83 ```