{"id":13542457,"url":"https://github.com/eclipse-bluechi/bluechi","last_synced_at":"2025-06-28T17:12:08.987Z","repository":{"id":63998585,"uuid":"564335533","full_name":"eclipse-bluechi/bluechi","owner":"eclipse-bluechi","description":"Eclipse BlueChi is a systemd service controller intended for multi-node environments with a predefined number of nodes and with a focus on highly regulated ecosystems such as those requiring functional safety.","archived":false,"fork":false,"pushed_at":"2025-05-27T12:51:46.000Z","size":5992,"stargazers_count":135,"open_issues_count":24,"forks_count":41,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-27T13:48:07.158Z","etag":null,"topics":["containers","controller","linux","podman","services","systemd"],"latest_commit_sha":null,"homepage":"https://bluechi.readthedocs.io/en/latest/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"alexlarsson/orch","license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-bluechi.png","metadata":{"files":{"readme":"README.developer.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-10T13:54:14.000Z","updated_at":"2025-05-27T12:51:49.000Z","dependencies_parsed_at":"2023-09-26T16:58:19.439Z","dependency_job_id":"68952fe4-e11d-4227-8c0b-abfb3df5421c","html_url":"https://github.com/eclipse-bluechi/bluechi","commit_stats":null,"previous_names":["containers/hirte","containers/bluechi"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-bluechi/bluechi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-bluechi%2Fbluechi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-bluechi%2Fbluechi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-bluechi%2Fbluechi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-bluechi%2Fbluechi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-bluechi","download_url":"https://codeload.github.com/eclipse-bluechi/bluechi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-bluechi%2Fbluechi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262465830,"owners_count":23315646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","controller","linux","podman","services","systemd"],"created_at":"2024-08-01T10:01:08.074Z","updated_at":"2025-06-28T17:12:08.967Z","avatar_url":"https://github.com/eclipse-bluechi.png","language":"C","funding_links":[],"categories":["C","linux"],"sub_categories":[],"readme":"# Eclipse BlueChi\u0026trade;\n\n- [Development](#development)\n  - [Environment Setup (Fedora / CentOS Stream)](#environment-setup)\n    - [Prerequisites (CentOS Stream only)](#prerequisites)\n    - [Dependencies Installation](#dependencies-installation)\n  - [Busctl](#busctl)\n  - [Code Style](#code-style)\n  - [Linting](#linting)\n  - [Build](#build)\n    - [Build options](#build-options)\n    - [Bindings](#bindings)\n  - [Static Code Analysis](#static-code-analysis)\n  - [Debug](#debug)\n  - [Unit Tests](#unit-tests)\n  - [Integration Tests](#integration-tests)\n  - [Running](#running)\n    - [Assumed setup](#assumed-setup)\n    - [bluechi](#bluechi-controller)\n    - [bluechi-agent](#bluechi-agent)\n    - [bluechictl](#bluechictl)\n- [Documentation](#documentation)\n  - [Building MAN Pages](#building-man-pages)\n- [Packaging](#packaging)\n  - [RPM](#rpm)\n  - [DEB](#deb)\n\n## Development\n\n### Environment Setup (Fedora / CentOS Stream) {#environment-setup}\n\nIn order to develop the project on Fedora or CentOS Stream you need to install following dependencies.\n\n#### Prerequisites (CentOS Stream only) {#prerequisites}\n\nTo build the project on CentOS Stream you need to enable CodeReady Build and EPEL repositories:\n\n```bash\nsudo dnf install dnf-plugin-config-manager\nsudo dnf config-manager --set-enabled crb\nsudo dnf install -y epel-release\n```\n\n#### Dependencies installation\n\n```bash\nsudo dnf install \\\n    bzip2 \\\n    clang-tools-extra \\\n    gcc \\\n    gcc-c++ \\\n    git \\\n    golang-github-cpuguy83-md2man \\\n    make \\\n    meson \\\n    systemd-devel \\\n    selinux-policy-devel\n```\n\n[markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) can be used for static analysis of markdown files.\nCheck the [installation guide](https://github.com/DavidAnson/markdownlint-cli2#install) and use the most appropriate way\nof installation for your setup.\n\n### busctl\n\n**busctl** is a systemd tool to introspect and monitor the D-Bus bus. See below some examples using busctl with bluechi service.\n\n**Instrospect org.eclipse.bluechi**:\n\n```bash\n# busctl introspect \\\n         org.eclipse.bluechi \\\n         /org/eclipse/bluechi\n\nNAME                                TYPE      SIGNATURE RESULT/VALUE   FLAGS\norg.eclipse.bluechi.Controller         interface -         -              -\n.CreateMonitor                      method    -         o              -\n.DisableMetrics                     method    -         -              -\n.EnableMetrics                      method    -         -              -\n.GetNode                            method    s         o              -\n.ListNodes                          method    -         a(sos)         -\n.ListUnits                          method    -         a(sssssssouso) -\n.Ping                               method    s         s              -\n.SetLogLevel                        method    s         -              -\n.JobNew                             signal    uo        -              -\n.JobRemoved                         signal    uosss     -              -\norg.freedesktop.DBus.Introspectable interface -         -              -\n.Introspect                         method    -         s              -\norg.freedesktop.DBus.Peer           interface -         -              -\n.GetMachineId                       method    -         s              -\n.Ping                               method    -         -              -\norg.freedesktop.DBus.Properties     interface -         -              -\n.Get                                method    ss        v              -\n.GetAll                             method    s         a{sv}          -\n.Set                                method    ssv       -              -\n.PropertiesChanged                  signal    sa{sv}as  -              -\n```\n\n**Example calling ListNodes**:\n\n```bash\nexport SERVICE=\"org.eclipse.bluechi\"\nexport OBJECT=\"/org/eclipse/bluechi\"\nexport INTERFACE=\"org.eclipse.bluechi.Controller\"\nexport METHOD=\"ListNodes\"\n\n# busctl call \\\n\t\"${SERVICE}\" \\\n\t\"${OBJECT}\" \\\n\t\"${INTERFACE}\" \\\n\t\"${METHOD}\"\n\na(sos) 3 \"control\" \"/org/eclipse/bluechi/node/control\" \"online\" \"node1\" \"/org/eclipse/bluechi/node/node1\" \"online\" \"qm-node1\" \"/org/eclipse/bluechi/node/qm_2dnode1\" \"online\"\n```\n\n### Code Style\n\n[clang-format](https://clang.llvm.org/docs/ClangFormat.html) is used to enforce a uniform code style. The formatting\nof all source files can be checked via:\n\n```bash\n# only check for formatting\nmake check-fmt\n\n# apply formatting to files\nmake fmt\n```\n\nFor the most part, this project follows systemd coding style:\n[systemd-coding-style](https://github.com/systemd/systemd/blob/main/docs/CODING_STYLE.md). Also, this project borrows\nsome of the coding conventions from systemd. For example, function names pertaining to D-Bus services look like\n`bus_service_set_property()`.\n\n### Linting\n\n[clang-tidy](https://clang.llvm.org/extra/clang-tidy/) is used for static analysis of C source codes.\n[markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) is used for static analysis of markdown files.\n[flake8](https://flake8.pycqa.org/en/latest/) is used for format checking and linting of python code.\n\nThe following make targets simplify the usage of the different linting tools:\n\n```bash\n# using clang-tidy, lint all C source files\nmake lint-c\n\n# same as lint-c target, but auto-fix errors if possible\nmake lint-c-fix\n\n# using markdownlint-cli2, lint all markdown files\nmake lint-markdown\n\n# combines lint-c and lint-markdown\nmake lint\n```\n\n### Build\n\nThe project is using [meson](https://mesonbuild.com/) as its primary build system.\n\nThe binaries and other artifacts (such as the man pages) can be built via:\n\n```bash\nmeson setup builddir\nmeson compile -C builddir\n```\n\nAfter successfully compiling the binaries, they can be installed into a destination directory (by default\n`/usr/local/bin`) using:\n\n```bash\nmeson install -C builddir\n```\n\nTo install it into `builddir/bin` use:\n\n```bash\nmeson install -C builddir --destdir bin\n```\n\nAfter building, the following binaries are available:\n\n- `bluechi-controller`: the systemd service controller which is run on the main machine, sending commands to the agents\n  and monitoring the progress\n- `bluechi-agent`: the node agent unit which connects with the controller and executes commands on the node machine\n- `bluechi-proxy`: an internally used application to resolve cross-node dependencies\n- `bluechictl`: a helper (CLI) program to send an commands to the controller\n\n#### Build options\n\nBlueChi can be built with configurable options as listed in [meson_options.txt](./meson_options.txt). The value for\nthose settings can either be changed directly in the file or via\n\n```bash\n# assuming an initial \"meson setup builddir\"\nmeson configure -D\u003coption-name\u003e=\u003coption-value\u003e builddir\n```\n\nCurrent options include:\n\n- `with_analyzer`: This option enables the [gcc option for static analysis](https://gcc.gnu.org/onlinedocs/gcc-13.2.0/gcc/Static-Analyzer-Options.html)\n- `with_coverage`: This option ensures that BlueChi is built to collect coverage when running a BlueChi binary\n- `with_man_pages`: This option enables building man pages as a part of the project build\n- `with_selinux`: This option includes building the SELinux policy for BlueChi\n\n#### Bindings\n\nBindings for the D-Bus API of `BlueChi` are located in [src/bindings](./src/bindings/). Please refer to the\n[README.md](./src/bindings/README.md) for more details.\n\nA complete set of typed python bindings for the D-Bus API is auto-generated. On any change to any of the [interfaces](./data/),\nthese need to be re-generated via\n\n```bash\n./build-scripts/generate-bindings.sh python\n```\n\n### Static Code Analysis\n\nAdditional, static code analysis is applied when running the [unit tests in CI](./.github/workflows/unit-tests.yml) by\nenabling the meson option `with_analyzer`:\n\n```bash\nmeson configure -Dwith_analyzer=true builddir\n```\n\nSince the result of the analysis is heavily dependent on the compiler version, flags, etc., its recommended to build\nand run tests for BlueChi also in the [build-base](./containers/build-base):\n\n```bash\n# navigate into the bluechi directory\ncd bluechi\n\n# run build-base container and mount bluechi directory\npodman run -it -v ./:/var/bluechi quay.io/bluechi/build-base:latest\n\n# configure meson to enable code analysis and build the project\nmeson setup builddir\nmeson configure -Dwith_analyzer=true builddir\nmeson compile -C builddir\n```\n\n### Debug\n\nIn some cases, developers might need a debug session with tools like gdb, here an example:\n\nFirst, make sure **meson.build** contains **debug=true**.\n\nRebuild the BlueChi project with debug symbols included:\n\n```bash\nbluechi\u003e make clean\nbluechi\u003e meson install -C builddir --dest=bin\nbluechi\u003e gdb --args ./builddir/bin/usr/local/libexec/bluechi-controller -c /etc/bluechi/controller.conf\n```\n\n### Unit tests\n\nUnit tests can be executed using following commands:\n\n```bash\nmeson setup builddir\nmeson configure -Db_coverage=true builddir  # if you want to collect coverage data\nmeson compile -C builddir\nmeson test -C builddir\nninja coverage-html -C builddir  # if you want to generate coverage report\n```\n\nwill produce a coverage report in `builddir/meson-logs/coveragereport/index.html`\n\n### Integration tests\n\nAll files related to the integration tests are located in [tests](./tests/) and are organized via\n[tmt](https://tmt.readthedocs.io/en/stable/). How to get started with running and developing\nintegration tests for BlueChi is described in [tests/README](./tests/README.md).\n\n### Running\n\nThe following sections describe how to run the built application(s) locally on one machine. For this, the assumed setup\nused is described in the first section.\n\n#### Assumed setup\n\nThe project has been build with the following command sequence:\n\n```bash\nmeson setup builddir\nmeson compile -C builddir\nmeson install -C builddir --destdir bin\n```\n\nMeson will output the artifacts to `./builddir/bin/usr/local/`. This directory is referred to in the following sections\nsimply as `\u003cbuilddir\u003e`.\n\nTo allow `bluechi-controller` and `bluechi-agent` to own a name on the local system D-Bus, the provided configuration\nfiles need to be copied (if not already existing):\n\n```bash\ncp \u003cbuilddir\u003e/share/dbus-1/system.d/org.eclipse.bluechi.Agent.conf /etc/dbus-1/system.d/\ncp \u003cbuilddir\u003e/share/dbus-1/system.d/org.eclipse.bluechi.conf /etc/dbus-1/system.d/\n```\n\n**Note:** Make sure to reload the dbus service so these changes take effect: `systemctl reload dbus-broker.service` (or\n`systemctl reload dbus.service`)\n\n#### bluechi-controller\n\nThe newly built controller can simply be run via `./\u003cbuilddir\u003e/bin/bluechi-controller`, but it is recommended to use a\nspecific configuration for development. This file can be passed in with the `-c` CLI option:\n\n```bash\n./\u003cbuilddir\u003e/bin/bluechi-controller -c \u003cpath-to-cfg-file\u003e\n```\n\n#### bluechi-agent\n\nBefore starting the agent, it is best to have the `bluechi-controller` already running. However, `bluechi-agent` will\ntry to reconnect in the configured heartbeat interval.\n\nSimilar to `bluechi-controller`, it is recommended to use a dedicated configuration file for development:\n\n```bash\n./\u003cbuilddir\u003e/bin/bluechi-agent -c \u003cpath-to-cfg-file\u003e\n```\n\n#### bluechictl\n\nThe newly built `bluechictl` can be used via:\n\n```bash\n./\u003cbuilddir\u003e/bin/bluechictl COMMANDS\n```\n\n## Documentation\n\nFiles for documentation of this project are located in the [doc](./doc/) directory comprising:\n\n- [api examples](./doc/api-examples/): directory containing source files for different programming languages that use\n  the D-Bus API of BlueChi, e.g. for starting a systemd unit\n- [man](./doc/man/): directory containing the markdown files for generating the man pages\n  (see [Building MAN pages](#building-man-pages) for more information)\n- readthedocs files for building the documentation website of BlueChi (see [the README](./doc/README.md) for further information)\n- [diagrams.drawio](./doc/diagrams.drawio) file containing all diagrams used for BlueChi\n\n### Building MAN pages\n\nThe source markdown files for building the MAN pages are located in [doc/man](./doc/man/). For generating the MAN pages\nfrom the markdown files [go-md2man](https://github.com/cpuguy83/go-md2man) is being used. Install it via:\n\n```bash\nsudo dnf install golang-github-cpuguy83-md2man\n```\n\nAfter executing a `meson install` the MAN pages are located in the `man/man*` directories.\n\n## Packaging\n\n### RPM\n\nIn order to package BlueChi as an RPM the following dependencies are required:\n\n```bash\nsudo dnf install \\\n    jq \\\n    rpm-build\n```\n\nThe scripts used to create the SRPM and RPM may be found in [build-scripts](./build-scripts) directory. Executing\nfollowing command will create RPM packages for the current content of the project:\n\n```bash\nsudo ./build-scripts/build-rpm.sh\n```\n\nCreated RPM packages can be found under `artifacts/rpms*` subdirectories according to the timestamp of the execution.\n\nThe package build process can be adjusted using following environment variables:\n\n- `ARTIFACTS_DIR`\n  - A full path to a directory where the RPMs will be saved. The script will create the directory if it does not exist.\n- `SKIP_BUILDDEP`\n  - To skip installation of build dependencies this option should contain `yes` value.\n- `WITH_PYTHON`\n  - To skip building python bluechi modules this option should contain `0`. Default: `1`.\n- `WITH_COVERAGE`\n  - To start collecting coverage this option should contain `1`. Default: `0`.\n\nSo for example following command will skip build dependencies installation and store create RPM packages into `output`\nsubdirectory:\n\n```bash\nSKIP_BUILDDEP=yes ARTIFACTS_DIR=${PWD}/output ./build-scripts/build-rpm.sh\n```\n\n### DEB\n\nCreating the BlueChi `.deb` package is described in the [debian/README.md](./debian/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-bluechi%2Fbluechi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-bluechi%2Fbluechi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-bluechi%2Fbluechi/lists"}