diff options
| -rw-r--r-- | topics/deployment.gmi | 8 | ||||
| -rw-r--r-- | topics/guix-system-containers-and-how-we-use-them.gmi | 23 | ||||
| -rw-r--r-- | topics/systems/mailer-opensmtpd.gmi | 56 |
3 files changed, 84 insertions, 3 deletions
diff --git a/topics/deployment.gmi b/topics/deployment.gmi index b80f533..92a2c01 100644 --- a/topics/deployment.gmi +++ b/topics/deployment.gmi @@ -1,14 +1,20 @@ # Deploy GeneNetwork +# Description + This page attempts to document the deployment process we have for GeneNetwork. We use Guix system containers for deployment of CI/CD and the Guix configuration for the CI/CD container should be considered the authoritative reference. => https://github.com/genenetwork/genenetwork-machines/blob/main/genenetwork-development.scm +See also + +=> ./guix-system-containers-and-how-we-use-them.gmi + ## genenetwork2 -TODO. Volunteers welcome! + ## genenetwork3 diff --git a/topics/guix-system-containers-and-how-we-use-them.gmi b/topics/guix-system-containers-and-how-we-use-them.gmi index 3aa3f7a..22cfa3f 100644 --- a/topics/guix-system-containers-and-how-we-use-them.gmi +++ b/topics/guix-system-containers-and-how-we-use-them.gmi @@ -1,13 +1,25 @@ # Guix system containers and how we use them -Our preferred way to deploy long-running services is to use Guix system containers. Note that Guix system containers are different from guix shell containers (and the older guix environment containers). guix shell containers are meant for interactive use and are a poor fit for deployment. Other non-Guix ways such as running long-running processes in tmuxes, running long-running services from your development repository, etc. are unthinkably hacky and should not even be considered as a quick dirty way to get things done. +Our preferred way to deploy long-running services is to use Guix system containers. Note that Guix system containers are different from guix shell containers (and the older guix environment containers). guix shell containers are meant for interactive use and are a poor fit for long running services. Other non-Guix ways such as running long-running processes in tmuxes, running long-running services from your development repository, etc. are a quick dirty way to get things done. Note that system containers are quite a bit heavier - they are full Linux boots. + +Guix system containers are fully described by a configuration file that, among other things, specifies the services run in it. These scheme configuration files are built using `guix system container' and produce a script. This script, when run, starts the described container. -Guix system containers are fully described by a scheme configuration file that, among other things, specifies the services run in it. These scheme configuration files are built using `guix system container' and produce a script. This script, when run, starts the described container. ``` $ guix system container foo.scm /gnu/store/9ld75cjg54xwqvsvvgdd38rv3d4x4wzz-run-container ``` +One cool aspect is that system containers can be easily tested on your own laptop. +A great tutorial can be found at + +=> https://guix.gnu.org/cookbook/en/html_node/Guix-System-Containers.html + +A system container comes with a running shepherd process and running services are explicitly configured. + +Our most important containers are defined in + +=> https://github.com/genenetwork/genenetwork-machines/blob/main/genenetwork-development.scm + ## Share network with the host Usually, we want the container to share the network with the host. So, we add the --network flag. @@ -25,10 +37,13 @@ $ guix system container --network --share=/var/lib/foo foo.scm ## systemd services to manage the container processes Now, running these container scripts directly from the command-line, probably from within a tmux, makes for a very fragile deployment. So, we symlink the script into /usr/local/bin and set up a systemd service to manage the container process. + ``` # ln --force --symbolic $(guix system container --network --share=/var/lib/foo foo.scm) /usr/local/bin/foo-container ``` + A systemd service file foo-container.service for this container should be put at /etc/systemd/system/. + ``` [Unit] Description = Run foo container @@ -39,17 +54,21 @@ ExecStart = /usr/local/bin/foo-container [Install] WantedBy = multi-user.target ``` + This allows us to start, stop and enable (for starting at boot time) the container easily. + ``` # guix system start foo-container # guix system stop foo-container # guix system enable foo-container ``` + With our service enabled to start at boot time, we need not worry about reboots. All our containers, and the services contained therein, start up smoothly on boot. ## Register as garbage collector root Finally, we must also tell Guix not to accidentally garbage collect our container or any of its dependencies. To this end, we symlink it into /var/guix/gcroots. + ``` # ln --force --symbolic /usr/local/bin/foo-container /var/guix/gcroots ``` diff --git a/topics/systems/mailer-opensmtpd.gmi b/topics/systems/mailer-opensmtpd.gmi new file mode 100644 index 0000000..6463c91 --- /dev/null +++ b/topics/systems/mailer-opensmtpd.gmi @@ -0,0 +1,56 @@ +# OpenSMTPD + +We have been using postfix and exim on different servers. Now it may be the time to switch to opensmtpd as it is modern, secure and easier to configure. Guix comes with a default opensmtp service, so let's try and get that running as a system container for reasons of deployment. See also + +=> ../deployment.gmi + +Setting up a mail service with Guix is described in + +=> https://guix.gnu.org/en/manual/devel/en/html_node/Mail-Services.html + +A service is defined as + +```scheme +(service opensmtpd-service-type + (opensmtpd-configuration + (config-file (local-file "./my-smtpd.conf")))) +``` + +A first attempt at running a container is + +``` +(use-modules (gnu) + (gnu services mail)) + +(operating-system + (host-name "mail") + (timezone "UTC") + (locale "en_US.utf8") + (bootloader (bootloader-configuration + (bootloader grub-bootloader) + (targets (list "/dev/sdX")))) + (file-systems %base-file-systems) + (users %base-user-accounts) + (packages %base-packages) + + (services (cons + (service opensmtpd-service-type + (opensmtpd-configuration + (config-file %default-opensmtpd-config-file + ; (config-file (local-file "./my-smtpd.conf"))) + ))) + %base-services))) +``` + +Running + +``` +guix system container opensmtpd.scm +/gnu/store/n6ap881jp3lgms35z0dyw4mnkkqsnm89-run-container +``` + +creates a container file that can be started with the returned launcher, e.g. as root + +``` +/gnu/store/n6ap881jp3lgms35z0dyw4mnkkqsnm89-run-container +``` |