142 lines
5.6 KiB
Org Mode
142 lines
5.6 KiB
Org Mode
#+TITLE: Guix Builder
|
|
#+AUTHOR: Collin J. Doering
|
|
|
|
#+begin_abstract
|
|
This repository defines a minimal OCI container containing guix and a few other tools useful
|
|
for CI/CD jobs. The container is expected to be run from a system that already has the
|
|
~guix-daemon~ installed and running, and is most useful in the context of existing CI/CD
|
|
tools that already use an existing OCI container runtime (eg. docker, podman, etc..).
|
|
#+end_abstract
|
|
|
|
* Prerequisites
|
|
|
|
- ~guix-daemon~ installed and running on the host
|
|
- ~dockerd~ to build and run the produced image
|
|
- ~direnv~ (optional)
|
|
|
|
* Repository Structure
|
|
|
|
- ~channels.scm~ :: [[*Guix Channel File][Guix Channel File]].
|
|
- ~Dockerfile~ :: From scratch image that uses guix pack tar.gz output.
|
|
- ~Makefile~ :: Various make targets to build and run the guix-builder OCI image.
|
|
- ~manifest-dev.scm~ :: Packages required for development.
|
|
- ~manifest.scm~ :: Packages to be installed in the OCI image.
|
|
- ~.gitignore~ :: Files ignored by git.
|
|
- ~README.org~ :: Org-mode[fn:1] documentation.
|
|
- ~shell.sh~ :: Launch a containerized development shell.
|
|
|
|
** Guix Channel File
|
|
|
|
Guix channels[fn:2] allow for Guix to be customized and extended. They are also critical for
|
|
replicating a Guix system[fn:3]. To ensure reproducibility, a ~channels.scm~ file is provided
|
|
in this repository that is expected to be used during deployment. It pins external guix
|
|
channels to specific versions.
|
|
|
|
* Setup development environment
|
|
~direnv~ is the preferred and optimal way to enter a development environment. Use ~direnv allow~.
|
|
|
|
Alternatively, ~./shell.sh~ can be invoked directly
|
|
|
|
* Building the image
|
|
|
|
#+begin_src shell
|
|
make [build]
|
|
#+end_src
|
|
~build~ is optional, as its the default target.
|
|
|
|
* Testing and using the image locally
|
|
|
|
The easiest way to use and test the guix-builder container image is to use the provide make
|
|
target.
|
|
|
|
#+begin_src shell
|
|
make run
|
|
#+end_src
|
|
|
|
Or, if you want to run in a container with no guix store mounted.
|
|
|
|
#+begin_src shell
|
|
make run-no-store
|
|
#+end_src
|
|
|
|
* Using the image
|
|
|
|
Now that the OCI image has been produced, some care must be taken when running it. Namely,
|
|
the following volumes are expected to be mounted.
|
|
|
|
- ~/var/guix/daemon-socket/socket~ :: the ~guix-daemon~ socket
|
|
- ~/gnu/store~ :: The hosts guix store
|
|
|
|
Additionally, for ~guix~ to function appropriately, the ~HOME~ environment variable must be
|
|
set. This allows guix to store its cache (mandatory for many operations, eg ~guix pull~).
|
|
Depending on use-case, it is sometimes useful to retain the guix cache between container
|
|
invocations. To do so, mount a volume to ~$HOME/.cache/guix~ (replacing ~$HOME~ with what it
|
|
will be set to within the container).
|
|
|
|
SSL certificates are included and configured for use in the container (via the ~nss-certs~
|
|
package). Its not supported to use your hosts certificates, as they may be incompatible with
|
|
openssl inside of the container.
|
|
|
|
A complete example is given below, where the aforementioned volumes are mounted, ~HOME~ is
|
|
set to ~/tmp~, and a volume for retaining the guix cache between invocations is put in place.
|
|
The working directory within the container is also set with the ~-w~ option, however this is
|
|
not required.
|
|
|
|
#+begin_src shell
|
|
docker run --rm -it \
|
|
-v /var/guix/daemon-socket/socket:/var/guix/daemon-socket/socket \
|
|
-v /gnu/store:/gnu/store:ro \
|
|
-v /var/lib/ci/guix-cache:/tmp/.cache/guix \
|
|
-e HOME=/tmp \
|
|
-w /tmp \
|
|
guix-builder:latest
|
|
#+end_src
|
|
|
|
** Using the image with Gitea/Forgejo actions or DroneCI/WoodpeckerCI
|
|
|
|
The primary use-case for the image produced by this repository is for ci/cd jobs (mandatorily
|
|
on a host that is running guix-daemon itself). This allows for the hosts guix store to be
|
|
reused, allowing for a node-local caching layer, and enabling optimal ci/cd build/deploy
|
|
times.
|
|
|
|
Any ci/cd tool that can run OCI containers should be compatible with this image, though the
|
|
optimal setup assumes it provides a mechanism to mount volumes and set environment variables
|
|
(by an administrator). Both DroneCI and WoodpeckerCI allow for this, using
|
|
~DRONE_RUNNER_VOLUMES~ and ~WOODPECKER_BACKEND_DOCKER_VOLUMES~ respectively. Gitea/Forgejo
|
|
actions allow it via the ~container.options~ configuration value.
|
|
|
|
Note, in WoodpeckerCI, this functionality has not yet made it into a release (see [[https://github.com/woodpecker-ci/woodpecker/pull/1203][PR]]).
|
|
|
|
* FAQ
|
|
|
|
** Why not produce this image with ~guix pack -f docker ...~ directly?
|
|
|
|
One may ask, why not simply produce a OCI container using ~guix pack~ directly? Eg.
|
|
|
|
#+begin_src shell
|
|
guix pack -f docker -S /bin=bin --entry-point=bin/guix -m manifest.scm
|
|
#+end_src
|
|
|
|
Well, I'm glad you asked! This produces a container that has the guix store in its default
|
|
location ~/gnu/store~. Using the same method as described in [[*Using the image with DroneCI / WoodpeckerCI][Using the image with DroneCI /
|
|
WoodpeckerCI]], this container image works, however it has an implicit constraint: all store
|
|
items used within the pack must also exist in the hosts guix store. This is because the guix
|
|
store is volume mounted into the container at runtime, shadowing the already existing
|
|
~/gnu/store~ directory put in place via ~guix pack~. There are ways one could work around
|
|
this constraint, however the best solution would be to have a guix container that is
|
|
independent of the host (as described in this repository).
|
|
|
|
** What about running a ~guix-daemon~ within a container (so that builds can be completely isolated)?
|
|
|
|
This currently is not possible ... TBD (more detail)
|
|
|
|
* Footnotes
|
|
|
|
[fn:1] https://orgmode.org/
|
|
|
|
[fn:2] https://guix.gnu.org/manual/en/html_node/Channels.html
|
|
|
|
[fn:3] https://guix.gnu.org/manual/en/html_node/Replicating-Guix.html
|