Board: laptop, CI and container

The goal is to show one manifest feeding three places, a developer laptop, a CI runner and an OCI image, so a bug that appears in one can be reproduced in the others.

This page is drawn from https://flox.dev/docs/tutorials/ci-cd, https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/, https://flox.dev/docs/man/flox-containerize, https://flox.dev/docs/concepts/flox-vs-containers, https://flox.dev/docs/man/flox-auth and https://flox.dev/docs/concepts/service-accounts.

Whiteboard outcome

When you are done, the board shows a .flox folder at the left with three arrows: to a laptop (flox activate), to a CI runner (install action, then activate action) and to a container image (flox containerize), with a credential note on the CI arrow.

Before you draw: three questions

1. Which CI platform runs the build: GitHub Actions, CircleCI, GitLab, something else?
2. Is the production artifact a container image, and who builds the Dockerfile today?
3. Does the pipeline pull private FloxHub environments or private catalog packages?

Draw it in 8 steps

1. On the left, draw the .flox folder in a repo. Say: “With Flox the exact same set of software can be used for local development and a CI/CD pipeline” (https://flox.dev/docs/tutorials/ci-cd).
2. Draw arrow one to a laptop labeled flox activate. Say: this is the board from the new-hire page. The environment is a path environment in the repo (https://flox.dev/docs/concepts/environments).
3. Draw arrow two to a CI runner. Say: on GitHub Actions use flox/install-flox-action, then flox/activate-action with a command, and note that the install action “is still required if you want to use” the activate action (https://flox.dev/docs/tutorials/ci-cd).
4. Write the other platforms under the runner. CircleCI has a Flox Orb with flox/install and flox/activate steps. GitLab uses the ghcr.io/flox/flox image and flox activate -c "<your command>" (https://flox.dev/docs/tutorials/ci-cd).
5. Draw a key on the CI arrow. Say: a pipeline that only uses an environment committed to the repository “needs no credentials at all”. For FloxHub environments, private catalogs or publishing, give the pipeline a service account token in the FLOX_FLOXHUB_TOKEN variable (https://flox.dev/docs/tutorials/ci-cd). A read-only service account “can pull environments and install packages but cannot push or publish” (https://flox.dev/docs/tutorials/ci-cd). Scripted login also exists: flox auth login --token-file “does not open a browser or prompt for input” (https://flox.dev/docs/man/flox-auth).
6. Draw arrow three to an image labeled flox containerize. Say: the command will “Export a Flox environment as a container image”, written to a runtime, a file, or stdout (https://flox.dev/docs/man/flox-containerize). The ci-cd page lists it as a suggested CI step (https://flox.dev/docs/tutorials/ci-cd).
7. Beside the image, write what running it does. Interactive docker run -it starts a bash subshell with the packages set; non-interactive docker run lets you “run a command within the container without launching a subshell” (https://flox.dev/docs/man/flox-containerize). Image settings such as exposed-ports and cmd go in an experimental [containerize.config] table, so say so (https://flox.dev/docs/man/flox-containerize). On macOS, building an image needs a supported runtime (docker or podman) because a proxy container is used (https://flox.dev/docs/man/flox-containerize).
8. At the bottom, write the rule: One lock file, three consumers. If CI disagrees with a laptop, diff the lock, not the Dockerfile. (https://flox.dev/docs/concepts/environments, https://flox.dev/docs/concepts/flox-vs-containers)

flowchart LR
  M[.flox folder<br/>manifest.toml<br/>manifest.lock]
  M -->|flox activate| L[Laptop]
  M -->|install action<br/>then activate action| C[CI runner]
  M -->|flox containerize| I[OCI image]
  T[Service account token<br/>FLOX_FLOXHUB_TOKEN] -.private envs only.-> C
  I --> R[Container runtime<br/>docker or podman]

What can go wrong

• Drift is the thing CI catches. The Flox blog calls CI “a continuous, automated check against environment drift” (https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/).
• Personal tokens in CI. A personal access token carries the owner’s full access, and revoking it also ends that person’s CLI sessions, which is why the docs prefer service accounts (https://flox.dev/docs/tutorials/ci-cd).
• Dev vs run mode in images. flox containerize takes -m dev|run, overriding the manifest setting options.activate.mode (https://flox.dev/docs/man/flox-containerize). Run mode skips package profile.d scripts (https://flox.dev/docs/concepts/activation).
• Image size. No source gives a typical image size for flox containerize output [verify].

A real example

The Flox docs team uses this loop itself: the floxdocs repo has a CI workflow that checks out the code, installs Flox with flox/install-flox-action, activates the environment with flox/activate-action, builds with MkDocs and deploys to Netlify (https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/).

The script for the commands

flox activate -c "npm run build"            # same command on laptop, runner, container
flox containerize -f ./mycontainer.tar && docker load -i ./mycontainer.tar
flox containerize --runtime docker          # straight into docker

Commands are from https://flox.dev/docs/man/flox-containerize and https://flox.dev/docs/tutorials/ci-cd.

What they will ask