Add a Dockerfile and documentation to the project

[ngircd-alex.git] / doc / Container.md

diff --git a/doc/Container.md b/doc/Container.md
new file mode 100644 (file)
index 0000000..29cc848
--- /dev/null
+++ b/doc/Container.md
@@ -0,0 +1,82 @@
+# [ngIRCd](https://ngircd.barton.de) - Container How-To
+
+The ngIRCd daemon can be run as a containerized application, for example using
+Docker or Podman (the latter being preferred and used in the examples below).
+The container definition file, also known as "Docker file", is bundled with this
+distribution as `contrib/Dockerfile` and based on the official "stable-slim"
+container of the Debian project (see https://hub.docker.com/_/debian).
+
+## Building the container
+
+You can use the following command to build the ngIRCd container image:
+
+```bash
+podman build --format=docker -f contrib/Dockerfile .
+```
+
+The `Dockerfile` includes a `HEALTHCHECK` directive, which is not supported by
+the default OCI 1.0 image format, therefore we use the "docker" format here.
+
+If you are using Git, you can tag the built image like this (use the ID of the
+newly built image!):
+
+```bash
+podman tag <container_id> "ngircd:$(git describe --tags | sed 's/rel-//g')"
+```
+
+## Running the container
+
+You can use this command to run the ngIRCd container using Podman, for example:
+
+```bash
+podman run --name=ngircd --detach \
+  -p 127.0.0.1:6667:6667 \
+  ngircd:<tag>
+```
+
+This creates and starts a new container named "ngircd" from the image
+"ngircd:<tag>" (you habe to substitute _<tag>_ with the real tag name here!) and
+maps the host port 6667 on localhost to the port 6667 inside of the container.
+
+### Configuring the container
+
+The ngIRCd inside of the container is installed inside of `/opt/ngircd/` and the
+default drop-in directory is `/opt/ngircd/etc/ngircd.conf.d`. Therefore you can
+map a host folder to this drop-in directory inside of the container and place
+drop-in configuration file(s) in the host path like this:
+
+```bash
+mkdir -p /host/path/to/ngircd/conf.d
+touch /host/path/to/ngircd/conf.d/my.conf
+podman run --name=ngircd --detach \
+  -p 127.0.0.1:6667:6667 \
+  -v /host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d' \
+  ngircd:<tag>
+```
+
+### Testing the configuration
+
+As with the native daemon, it is a very good idea to validate the configuration
+of the daemon after making changes.
+
+With Docker and Podman, you can pass arguments to the `ngircd` binary inside of
+the container by simply appending it to the "run" command line like this:
+
+```bash
+podman run --name=ngircd --rm -it \
+  -v /host/path/to/ngircd/conf.d:/opt/ngircd/etc/ngircd.conf.d' \
+  ngircd:<tag>
+  --configtest
+```
+
+### Reloading the daemon configuration in a running container
+
+To activate changed configuration of ngIRCd, you can either restart the
+container (which will disconnect all currently connected clients) or signal
+`ngircd`(8) inside of the running container to reload its configuration file(s).
+
+The latter can be done with this command, for example:
+
+```bash
+podman exec -it ngircd /bin/bash -c 'kill -HUP $(/usr/bin/pidof -s ngircd)'
+```