Builder Developer Information

Setup

To start developing, clone the repo and run nix develop to install all python requirements:

git clone https://iglu-sh/iglu
cd iglu/builder/src
nix develop

For developing, we are usually setting dev_mode on in the config.toml:

echo <<EOF
[server]
dev_mode = true
EOF > config.toml

To start the builder:

python -m iglu_builder

General Dev Information

The Builder is written in Python using FastAPI, our Linter is Basedpyright and the files live in /builder.

The project structure is as follows:

• config.toml.example: Example config.toml
• pyproject.toml: PyProject file, which is needed to build the application
• /src/iglu_builder/*.py: Classes and components that actually do something
• /src/iglu_builder/static: All static pages live here
• /src/iglu_builder/types/*.py: Types that do not much, except being types (sometimes with default values)
• /src/iglu_builder/templates/*.j2: All needed jinja2 templates will go here

Api (routes) Structure

We follow these route sturctures:

• /api/v1/*: here are any REST-API and Websocket endpoints
• /: this is a small welcome page with a simple test interface
• /docs: from FastAPI generated api documentation

Configuration Parameters

The iglu builder configuration is written in TOML. This is what the different parameters actually do:

[builder]

Key	Values	Default	Description
work_dir	<path>	/tmp/iglu_builder	Path where are the jobs get executed
allowed_commands	<list<strings>>	["nix", "nix-build"]	Defines which commands can be executed by a build job

[server]

Key	Values	Default	Description
dev_mode	<bool>	false	If true the webserver refreshes after file change
port	<int>	8000	The port on which the server is listening
host	<string>	0.0.0.0	The host on which the server is listening

Example config

[builder]
work_dir = "/tmp/iglu_builder"
allowed_commands = ["nix", "nix-build"]

[server]
port = 8000
host = "localhost"
dev_mode = true

Starting a build process

To start a build process you have to follow this short manual:

1. start developing mode: cd builder fastapi dev
2. connect to websocket via http://localhost:8000/api/v1/build
3. send a builder config via this websocket
4. wait until your build has fnished

Builder-Job schema

Key	Values	Description
command	<list<string>>	Command to execute seperated as list. This command hast to start with nix or nix-build
repo.url	<string>	Url of the git repository
repo.branch	<string>	Optional parameter to select a specific branch, if not set the default branch will be cloned
cache.url	<string>	Url of the cachix compatible cache
cache.auth_token	<string>	The authtoken of the cachix compatible cache
cache.signing_key	<string>	The signingkey which is used to sign every derivation

Example job

{
    "command": ["nix", "build", ".#nixosConfigurations.SYSTEM.config.system.build.toplevel"],
    "repo": {
        "url": "https://github.com/your/repo",
        "branch": "my-branch"
    },
    "cache": {
        "url": "https://cache.example.com/cache",
        "auth_token": "your_super_secret_token",
        "signing_key": "your_super_secret_signing_key"
    }
}