openmamba-docker-buildvm/README.md

docker image for openmamba buildvm

This project provides a Dockerfile and related files which can be easily used to create a Docker image and container set up with autodist and webbuild with the purpose to maintain and build openmamba RPM packages.

The project can be used on any O.S. with docker installed and supporting one of the following platforms:

• linux/amd64 (x86_64)
• linux/arm64 (aarch64)
• linux/386 (i586)

Docker installation

When using openmamba as docker host you may first need to install it with:

sudo dnf install docker

Then it is recommended adding your user to the docker group (replace <username> with your username):

sudo usermod -aG docker <username>

Upon install you may need to start docker socket with:

sudo systemctl start docker.socket

Installation

Building the image is recommented via docker-buildx so you may first need to install it with:

sudo dnf install docker-buildx

Create buildvm image with:

docker buildx build -t buildvm --platform linux/amd64 .

Create and start a new container with:

docker run --name buildvm --hostname buildvm -d -p 4567:80 -p 8567:8021 buildvm

A different name (replace any or all occurencies of buildvm in the two commands above) and local port mapping (replace 4567/8567) may be used as needed. 4567:80 exposes webbuild (Apache); 8567:8021 exposes autodistd's own API (see "autodistd" below) -- omit it if you don't need to reach autodistd from outside the container.

x86 image on x86_64 host

Use the file Dockerfile-i586 to install a x86 image to be run on x86_64 host:

docker buildx build -t buildvm-i586 --platform linux/386 -f Dockerfile-i586 .

Container management

Stop with:

docker stop buildvm

Restart with:

docker start buildvm

Backup and recreation

Recreating a container (e.g. after a Dockerfile/rootfiles change, such as the image needing a rebuild) loses anything written inside the container's own filesystem, since none of it is kept in a Docker volume. The following paths hold state that isn't part of the image and must be backed up before removing a container and restored into the new one:

• /etc/autodist -- autodist configuration, including secrets (config-git, secrets)
• /var/autodist/.claude -- Claude Code session data for the autodist user, if used
• /var/autodist/.autospec -- autospec user configuration
• /var/webbuild/users/ -- per-user webbuild accounts (the default admin.conf is reinstalled by the autodist-webbuild package and doesn't need backing up on its own, but any other file there does)

Recommended procedure, replacing buildvm with the actual container name (e.g. buildvm-rebuilds):

1. Back up the paths above from the running container into a local directory mirroring their absolute path, e.g. under configs/buildvm/ (add configs/ to .gitignore -- some of these files contain credentials and must not be committed):

mkdir -p configs/buildvm/etc configs/buildvm/var/autodist configs/buildvm/var/webbuild
docker cp buildvm:/etc/autodist configs/buildvm/etc/
docker cp buildvm:/var/autodist/.claude configs/buildvm/var/autodist/
docker cp buildvm:/var/autodist/.autospec configs/buildvm/var/autodist/.autospec
docker cp buildvm:/var/webbuild/users configs/buildvm/var/webbuild/

2. Stop and remove the container:

docker stop buildvm
docker rm buildvm

3. Rebuild the image if Dockerfile/rootfiles changed, then recreate the container (see "Installation" above for the docker buildx build/docker run commands).

4. Restore the backed-up paths into the new container:

docker cp configs/buildvm/etc/autodist buildvm:/etc/
docker cp configs/buildvm/var/autodist/.claude buildvm:/var/autodist/
docker cp configs/buildvm/var/autodist/.autospec buildvm:/var/autodist/.autospec
docker cp configs/buildvm/var/webbuild/users buildvm:/var/webbuild/

5. docker cp preserves the numeric UID/GID of the source files as-is, which may not match the expected owner in the new container (e.g. everything lands owned by root if it was copied out via --user root). Fix ownership afterwards, running as root inside the container:

docker exec --user root buildvm chown -R root:autodist /etc/autodist
docker exec --user root buildvm chown apache:autodist /etc/autodist/secrets
docker exec --user root buildvm chown -R autodist:autodist /var/autodist/.claude /var/autodist/.autospec
docker exec --user root buildvm chown -R apache:nobody /var/webbuild/users

Check the actual expected owners with ls -la on each path before assuming the ones above -- they can differ between images/versions. /etc/autodist/secrets is the one exception inside /etc/autodist: it's owned by apache, not root, since Apache/autodist-webbuild reads it directly.

Usage

autodistd

The container's CMD is buildvm-init (rootfiles/usr/local/bin/buildvm-init), not apachectl or autodistd directly. tini (the container's ENTRYPOINT) only ever supervises one process, so that one process's job is to start both Apache and autodistd and keep them running underneath it -- if either one dies (crash, or a deliberate pkill to pick up a package update), it gets restarted immediately, without tini ever noticing or the container needing to restart. See the script itself for the full reasoning, and the autodist repository's autodistd/README.md for the API/scheduler docs.

autodistd listens on port 8021 inside the container; see -p 8567:8021 in the docker run command above to reach it from outside.

Configuration (API key, start-paused, port) is read by autodistd from /etc/autodist/autodistd inside the container, not from docker run -e/environment variables -- fill it in with docker exec buildvm sh -c '...' if write access to the API is needed (see the autodist repository's autodistd/README.md, "Configuration").

Webbuild web interface

With a browser access the webbuild interface at:

http://localhost:4567

To access from another host you may replace localhost with the container host (remember to check that exposed port is open in firewall).

Login with the following credentials:

• Username: autodist
• Password: openmamba

Remote host and different port mapping may be used as needed.

Spawn a shell into the running container with:

docker exec -it --user root buildvm /bin/bash

Or as autodist user:

docker exec -it --user autodist buildvm /bin/bash

If using x86 container on x86_64 host commands need to be prefixed by linux32:

docker exec -it --user autodist buildvm-i586 linux32 /bin/bash

Configure container for automatic start and resource limits

Set the container for automatic start on Docker service restart or host reboot with the following command:

docker update --restart unless-stopped buildvm

You may limit the CPU and memory usage of the container with the following command:

docker update --cpuset-cpus="0-3" --cpus="4" --memory="8g" buildvm

Autoport cron job

autoport is specifically intented for openmamba maintainer to port packages to required architectures. The involved configuration is file:

/etc/sysconfig/autoport

Autoport needs to be globally enabled with setting:

AUTOPORT_ENABLE=1

Port configurations are defined in the same file inside array variables, in this example we use the first configuration with array index of 0:

AUTOPORT_ARCH[0]=aarch64
AUTOPORT_DISABLE[0]=
AUTOPORT_CHROOT_USER[0]=autodist
AUTOPORT_NATIVE[0]=1
AUTOPORT_REPOSITORIES[0]="devel-makedist devel-kernel devel-autodist devel-misc"
AUTOPORT_PORT_REPOSITORY[0]="#SELF"
AUTOPORT_BASE_REPOSITORY[0]="devel-autodist"
AUTOPORT_IMPORT_REPOSITORIES[0]="$AUTOPORT_DEVEL_IMPORT_REPOSITORIES"

The command to run autoport batch process for configuration with index 0 is:

docker exec -it buildvm /usr/bin/autoport-launcher 0

Maintainer wants to add autoport as a cron job. To do this you may set the cron job on the docker host by running crontab -e and adding the line:

0 * * * * docker exec buildvm /usr/bin/autoport-launcher 0 2>&1 | logger -t autoport0

This whole cron entry is meant to be temporary anyway -- autodistd's own scheduler is meant to replace it, see the autodist repository's autodistd/README.md.

You may see a resume of port processes by opening the page:

http://localhost:4567/autobuilds.html