commit daa240f5c5cb12d34d927d35dfe9c74c4500420f
Author: Alex Maldonado <alex@scient.ing>
Date:   Fri Aug 7 13:39:56 2026 -0400

    Initial commit

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..d57ee22
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,77 @@
+# syntax=docker/dockerfile:1
+#
+# Gitea Actions job-container image for building Rust projects with pixi.
+#
+# The job never downloads the Rust toolchain: the compiler, C toolchain, and
+# pkg-config are baked into pixi's package cache at build time, so `pixi install`
+# in a job only links them into the environment instead of fetching them. sccache
+# is included so unchanged dependencies are served from a cache instead of being
+# recompiled every run.
+
+FROM node:26-trixie-slim@sha256:a1d9d671994fc2d26e297ac56b4b1522a8bc7fa71c43b14cd1b1fe6c5116f7dc
+
+# node is here because Gitea's JavaScript actions (actions/checkout and friends)
+# need it. git and ca-certificates are for checkout; curl is for the release API
+# calls in the workflows. The C compiler is not installed here: pixi brings it.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    git ca-certificates curl \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/prefix-dev/pixi:0.76.1 /usr/local/bin/pixi /usr/local/bin/pixi
+
+# --- Bake the Rust toolchain into pixi's package cache ---
+# PIXI_CACHE_DIR is the shared store of downloaded conda packages. Point it at a
+# stable path and pre-fill it by installing a throwaway environment that pins the
+# same toolchain your projects use. At job time, pixi finds these packages
+# already unpacked here and hardlinks them into .pixi/envs with no download. Keep
+# RUST_VERSION in step with the projects' pixi.toml; rebuild the image when it
+# moves.
+ENV PIXI_CACHE_DIR=/opt/pixi/cache
+ARG RUST_VERSION=">=1.96.0,<1.97"
+RUN <<EOF
+set -eux
+mkdir -p /opt/pixi/seed
+cd /opt/pixi/seed
+cat > pixi.toml <<TOML
+[workspace]
+name = "seed"
+version = "0.0.0"
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+[dependencies]
+rust = "${RUST_VERSION}"
+c-compiler = "*"
+pkg-config = "*"
+TOML
+pixi install
+# Keep the warmed cache at /opt/pixi/cache; drop the throwaway environment.
+rm -rf /opt/pixi/seed/.pixi
+EOF
+
+# --- sccache: cache compiled crates across job runs ---
+# The toolchain is baked, but each job still recompiles dependencies unless the
+# output is cached. sccache stores compiled artifacts keyed by their inputs, so
+# unchanged crates are copied from cache instead of rebuilt. This only helps if
+# SCCACHE_DIR and CARGO_HOME persist between jobs, which the named volumes below
+# provide.
+ARG SCCACHE_VERSION=0.17.0
+ARG SCCACHE_SHA256=67c4a96dd237c1f518f6b36083f270f9976d516f1e57fce891755ea782e50006
+RUN <<EOF
+set -eux
+cd /tmp
+asset="sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl"
+curl -fsSLO "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/${asset}.tar.gz"
+echo "${SCCACHE_SHA256}  ${asset}.tar.gz" | sha256sum -c -
+tar -xzf "${asset}.tar.gz"
+install -m 0755 "${asset}/sccache" /usr/local/bin/sccache
+rm -rf "${asset}" "${asset}.tar.gz"
+EOF
+
+ENV CARGO_HOME=/opt/cargo \
+    SCCACHE_DIR=/opt/sccache \
+    SCCACHE_CACHE_SIZE=2G \
+    RUSTC_WRAPPER=sccache \
+    CARGO_INCREMENTAL=0
+RUN mkdir -p /opt/cargo /opt/sccache
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..21702aa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# pixi-build-rust
+
+The container image the Gitea Actions runner uses to build Rust projects with pixi.
+
+## What it is
+
+A push to a Rust project runs its CI, nightly, and release workflows on a runner, and every one of those jobs needs the same Rust toolchain.
+This image is the environment those jobs run in.
+
+It is deliberately not small.
+The runner host has one vCPU and a gigabyte of memory, so the slow parts of a build are downloading the toolchain and compiling from scratch.
+This image front-loads both: the compiler is already in pixi's package cache before any job starts, and sccache is present so unchanged dependencies come from a cache instead of a rebuild.
+A job that would otherwise spend minutes fetching rustc and gcc spends none.
+
+Node runs the JavaScript actions Gitea uses to bootstrap a job, such as `actions/checkout`.
+`git` performs the clone, commit, and push, `ca-certificates` lets it speak HTTPS, and `curl` is what the release workflow uses to call the Gitea API.
+The compiler is not installed through the system package manager; it comes from pixi, along with a C compiler and pkg-config.
+No credentials live in the image: the workflows authenticate with the built-in job token Gitea gives each run.
+
+The toolchain is baked by pointing `PIXI_CACHE_DIR` at a fixed path and installing a throwaway environment at build time that pins the same `rust` version the projects use.
+pixi stores the downloaded packages there, and a job's `pixi install` then hardlinks them into place without a download.
+Keep the `RUST_VERSION` build argument in step with the projects' `pixi.toml`, and rebuild when it moves.
+
+## Build
+
+Build the image on your own machine and push it to Gitea's container registry.
+The runner only ever pulls it.
+
+You will need an access token with `package:write` access.
+Authenticate Docker with it, then build for `linux/amd64`, since that is what the runner host is.
+Architecture matters more here than for a lighter image: the toolchain pixi installs is built for glibc on amd64, so an `arm64` image will push but fail to start with an exec-format error.
+
+```bash
+docker login git.scient.ing
+
+docker buildx build --platform linux/amd64 \
+  -t git.scient.ing/infra/pixi-build-rust:1 --push .
+```
+
+Bump the tag with a revision suffix (`:2`, `:3`) whenever the `Dockerfile` changes, including when you move the pinned `rust` or `sccache` version.
+The image is always pulled by an explicit version, never `latest`, so a runner's behavior stays tied to a named artifact you can roll back to.
+
+## Use
+
+A runner advertises a label that maps to this image, and a project's workflows select it with `runs-on`.
+
+```yaml
+# in the runner's config.yaml
+runner:
+  labels:
+    - "pixi-build-rust:docker://git.scient.ing/infra/pixi-build-rust:1"
+```
+
+```yaml
+# in each Rust repository's .gitea/workflows/*.yml
+jobs:
+  build:
+    runs-on: pixi-build-rust
+```
+
+The baked cache makes the first job on a fresh container fast, but job containers are removed when they finish, so anything a job writes is gone by the next run.
+To keep the crate registry and the compile cache between runs, mount them as named volumes in the runner's `config.yaml`.
+
+```yaml
+# in the runner's config.yaml
+container:
+  options: >-
+    -v pixi-cache:/opt/pixi/cache
+    -v cargo-home:/opt/cargo
+    -v sccache:/opt/sccache
+```
+
+Docker fills an empty named volume from the image's contents at that path the first time it is used, so the baked toolchain is present on the first job and the volume holds any later changes.
+That is runner configuration, not part of this image.
\ No newline at end of file