From: Alexander Barton Date: Fri, 9 Feb 2024 21:58:44 +0000 (+0100) Subject: Add a Dockerfile and documentation to the project X-Git-Tag: rel-27-rc1~43 X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=ngircd-alex.git;a=commitdiff_plain;h=934f3a0d88becd5f0434e0d1a1cf8f3195c6486d Add a Dockerfile and documentation to the project --- diff --git a/.dockerignore b/.dockerignore new file mode 120000 index 00000000..3e4e48b0 --- /dev/null +++ b/.dockerignore @@ -0,0 +1 @@ +.gitignore \ No newline at end of file diff --git a/Makefile.am b/Makefile.am index 3ec3965b..e529f79a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -18,6 +18,7 @@ EXTRA_DIST = \ autogen.sh \ configure.ng \ .clang_complete \ + .dockerignore \ .mailmap clean-local: diff --git a/contrib/Dockerfile b/contrib/Dockerfile new file mode 100644 index 00000000..33eab278 --- /dev/null +++ b/contrib/Dockerfile @@ -0,0 +1,62 @@ +# ngIRCd -- The Next Generation IRC Daemon +# Copyright (c)2001-2024 Alexander Barton (alex@barton.de) and Contributors + +# Build Container + +FROM docker.io/library/debian:stable-slim AS build +USER root +RUN apt-get -y update \ + && apt-get -y install --no-install-recommends \ + autoconf \ + automake \ + build-essential \ + expect \ + gawk \ + git \ + libgnutls28-dev \ + libident-dev \ + libpam0g-dev \ + openssl \ + pkg-config \ + telnet \ + zlib1g-dev \ + && mkdir -p /usr/local/src/ngircd /opt/ngircd \ + && chown bin:bin /usr/local/src/ngircd /opt/ngircd +WORKDIR /usr/local/src/ngircd +COPY . /usr/local/src/ngircd +RUN chown -R bin /usr/local/src/ngircd +USER bin +RUN ./autogen.sh --prefix=/opt/ngircd \ + --with-gnutls \ + --with-iconv \ + --with-ident \ + --with-pam \ + && make all \ + && make -C src/ngircd check \ + && make install \ + && printf \ + "# ngircd.conf\n\n[Global]\nServerGID=irc\nServerUID=irc\n\n[Options]\nIdent=no\nPAM=no\n\n[SSL]\nCAFile=/etc/ssl/certs/ca-certificates.crt\n" \ + >/opt/ngircd/etc/ngircd.conf \ + && chmod -R a+rX /opt/ngircd + +# Run container + +FROM docker.io/library/debian:stable-slim +USER root +RUN apt-get -y update \ + && apt-get -y install --no-install-recommends --no-install-suggests \ + ca-certificates \ + catatonit \ + libgnutls30 \ + libident \ + libpam0g \ + libwrap0 \ + zlib1g \ + && apt-get -y clean \ + && rm -rf /var/cache/debconf/*-old /var/lib/apt/lists/* +COPY --from=build /opt/ngircd /opt/ngircd +USER irc +ENTRYPOINT [ "/usr/bin/catatonit", "--", "/opt/ngircd/sbin/ngircd", "--nodaemon" ] +EXPOSE 6667 6697 +HEALTHCHECK --interval=30s --timeout=5s --retries=1 --start-period=5s \ + CMD [ "/usr/bin/grep", "-F", ":1A0B ", "/proc/net/tcp" ] diff --git a/contrib/Makefile.am b/contrib/Makefile.am index 27731b3f..f2d99012 100644 --- a/contrib/Makefile.am +++ b/contrib/Makefile.am @@ -14,6 +14,7 @@ SUBDIRS = Debian EXTRA_DIST = README.md \ de.barton.ngircd.metainfo.xml \ de.barton.ngircd.plist \ + Dockerfile \ ngindent.sh \ ngircd-bsd.sh \ ngIRCd-Logo.gif \ diff --git a/contrib/README.md b/contrib/README.md index 4f04dce6..fdd46495 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -9,6 +9,9 @@ This `contrib/` directory contains the following sub-folders and files: - `de.barton.ngircd.plist[.tmpl]`: launchd(8) property list file. +- `Dockerfile`: Container definition file, for Docker or Podman for example. + More information can be found in the `doc/Container.md` file. + - `ngindent.sh`: Script to indent the code of ngIRCd in the "standard way". - `ngircd-bsd.sh`: Start/stop script for FreeBSD. diff --git a/doc/Container.md b/doc/Container.md new file mode 100644 index 00000000..29cc848b --- /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 "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: +``` + +This creates and starts a new container named "ngircd" from the image +"ngircd:" (you habe to substitute __ 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: +``` + +### 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: + --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)' +``` diff --git a/doc/Makefile.am b/doc/Makefile.am index 91583f5c..a7e01999 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,6 +21,7 @@ static_docs = \ Bopm.txt \ Capabilities.txt \ Commands.txt \ + Container.md \ Contributing.txt \ FAQ.md \ HowToRelease.txt \