Skip to content

Contributing

Thanks for your interest in contributing to temBoard. temBoard is an open source project welcoming contribution from idea to code and more.

Submitting an Issue or a Patch

We use the dalibo/temboard GitHub project to track issues and review contributions. Fork the main repository and open a pull request against master branch as usual.

Cloning the Repository

Get temBoard UI and agent sources in one single repository:

$ git clone https://github.com/dalibo/temboard.git
$ cd temboard/

Directories Overview

dalibo/temboard git repository contains a few sub-projects. Here is a quick overview.

  • docs/ - Global mkdocs documentation sources.
  • ui/ - Python Tornado/Flask project for temBoard UI aka server.
  • agent/ - Bare Python project for temBoard agent.
  • toolkit/ - Shared library between agent and UI.
  • dev/ - Development scripts and data.
  • dev/bin/ - Development scripts.
  • docker/ - Quickstart Docker Compose file.
  • tests/ - Functional end to end tests.

Python package is temboardui for temBoard UI and temboardagent for temBoard agent.

Development Requirements

You need the following software to develop temBoard:

  • bash, git, make, psql.
  • Docker Compose v2.
  • uv.
  • NodeJS 20+ and npm for building some browser assets.

Setup Development

Running development version of UI and agent requires two terminals, one for each.

The develop make target builds assets, creates a virtual environment for Python 3.9, installs temBoard UI, its requirements, development tools, builds agent Docker image, starts docker services and initializes temBoard database.

$ make develop
dev/bin/mkenv > .env
git config blame.ignoreRevsFile dev/git-blame-ignore-revs
if [ -d ~/.config/lnav/formats ] ; then ln -fsTv $PWD/dev/lnav/formats ~/.config/lnav/formats/temboard ; fi
make -j 2 install-3.9 ui/build/bin/prometheus ui/build/bin/promtool
make[1] : on entre dans le répertoire « /home/bersace/src/dalibo/temboard »
uv venv --clear --python=python3.9 --prompt="temboard-py3.9"
...
✔ Container temboard-agent-stable-1     Started                                                                                                                                   5.5s


   You can now execute temBoard UI with uv run temboard

$ uv run temboard --debug
INFO:  app: Starting temboard. version=9.0.1
INFO:  app: Using config file /home/bersace/src/dalibo/temboard/.config/temboard.conf.
15:21:56 temboardui[243684] DEBUG:  model: Using PostgreSQL PostgreSQL 17.7 on x86_64-pc-linux-musl, compiled by gcc (Alpine 14.2.0) 14.2.0, 64-bit.
15:21:56 temboardui[243684] INFO:  migrator: temBoard database is up-to-date. revision=013_alerting-index.sql
...
15:21:57 temboardui[243684] INFO:  temboardui: Serving temboardui on http://0.0.0.0:8888
...

Go to http://localhost:8888/ to access temBoard running with your code!

You now need to run the agent. Open a second terminal to interact with the agent and execute the following commands.

$ docker compose exec agent0 uv run /bin/bash
root@91cd7e12ac3e:/var/lib/temboard-agent# sudo -Eu postgres temboard-agent
12:41:10 temboardagent[67] DEBUG:  app: Starting temboard-agent 9.0.dev0.
...

The agent is preregistered in UI, using host 0.0.0.0 and port 2345. The monitored Postgres instance is named postgres0.dev.

Beware that two Postgres instances are set up with replication. The primary instance may be either postgres0 or postgres1. See below for details.

Coding Style

An .editorconfig file configures whitespace and charset handling in various programming language. The EditorConfig site links to plugins for various editors. See .editorconfig for a description of the conventions. Please stick to these conventions.

Python syntax must conform to ruff. CI checks new code with ruff.

Javascript and CSS syntax should conform to prettier. It is recommended to configure your editor to automatically format on save. CI checks new code with prettier.

Make sure to be in ui/ directory to first check if files are already formatted:

npx prettier --check .
If necessary, you can then format your file: 
npx prettier --write temboardui/static/src/

You can optionally install husky pre-commit hooks.

cd ui
npm run install-husky

Executing in debug mode

temboard and temboard-agent commands has a debug mode. In debug mode, logs are verbose, files change triggers an automatic restart of the process, an unhandled exception drops in an interactive PDB debugger prompt.

Enable debug mode by setting DEBUG=y environment variable. For agent, only long running commands have autoreload.

psql for Monitored PostgreSQL

If you need to execute queries in monitored PostgreSQL instances, execute psql inside the corresponding agent container using the following command:

$ docker compose exec agent0 psql
psql (13.5 (Debian 13.5-0+deb11u1), server 14.1)
WARNING: psql major version 13, server major version 14.
         Some psql features might not work.
Type "help" for help.

postgres=#

Playing with Replication

Two postgres instances are up with replication. You can execute a second agent for it likewise:

$ docker compose exec agent1 /bin/bash
root@91cd7e12ac3e:/var/lib/temboard-agent# sudo -Eu postgres temboard-agent
 INFO: Starting temboard-agent 8.0.dev0.
 INFO: Found config file /etc/temboard-agent/temboard-agent.conf.
2022-01-11 10:12:55,130 [ 1568] [app             ] DEBUG: Looking for plugin activity.
...

bash history is shared amongst these two containers.

In UI, the second agent is pre-registered with address 0.0.0.0 and port 2346 instead of 2345. Second instance FQDN is postgres1.dev.

The script dev/bin/switchover.sh triggers a switchover between the two postgres instances. Executing dev/bin/switchover.sh one more time restore the original topology.

Testing previous version

Compose project for development configures a stable agent named agent-stable. This agent is preregistered in development UI. Browse postgres-stable instance in UI to ensure temBoard UI is compatible with stable agent.

Access Postgres instance monitored by stable agent using the following compose invocation:

$ docker compose exec agent-stable psql
psql (13.5 (Debian 13.5-0+deb11u1), server 13.7)
Type "help" for help.

postgres=#

Connect to the repository database

The own Postgres instance of the temBoard UI is exposed on the 5432 port of the host machine so that it can be accessed with:

$ PGPASSWORD=temboard psql -h localhost -U temboard temboard

Alternatively, it is also reachable with:

$ docker compose exec repository psql -U postgres temboard
psql (16.0)
Type "help" for help.

temboard=#

Choosing PostgreSQL Version

You can change the version of the monitored PostgreSQL instance by overriding image tag in docker-compose.override.yml.

docker-compose.override.yml
1
2
3
4
5
6
services:
  postgres0:
    image: postgres:9.5-alpine &postgres_image

  postgres1:
    image: *postgres_image

Now apply changes with make develop. Docker-compose will recreate postgres0 and agent0 containers, thus you need to start the agent as documented above.

Note that defining a different major version for postgres0 and postgres1 breaks physical replication.

Launching Multiple Agents

Default development environment instanciates two PostgreSQL instances and their temBoard agents. Root Makefile offers two targets to help testing big scale setup :

  • make mass-agents loops from 2348 to 3000 and instanciates a PostgreSQL instance for each number and an agent to monitor it. Number is used as agent port. Each instanciation requires you to type y and Enter. This allows to throttle instanciations and to stop when enough instances are up.
  • make clean-agents trashes every existing instances from 2348 to 3000, without interaction. make clean-agents does not unregister agents!

Execute Unit Tests

Each UI and agent projects has its own unit tests battery. Enable the virtualenv and use pytest to run unit tests:

$ . dev/venv-py3.9/bin/activate
$ pytest ui/tests/unit
...
==== 31 passed, 10 warnings in 1.10 seconds ======
$ pytest agent/tests/unit
...
=============== 6 passed in 0.25s ================
$

Execute Integration Tests

The tests/ directory contains a pytest project to tests UI and agent integration using Selenium.

On Debian your UNIX user must be in the ssl-cert group to run the tests. Be careful, the tests will use the local installation of temboard if it exists instead of dev files. To run the tests locally it is better not to have temboard installed.

Execute these tests right from your virtualenv, using pytest:

$ uv run pytest tests/
============================= test session starts ==============================
platform linux -- Python 3.9.25, pytest-8.4.2, pluggy-1.6.0 -- /home/bersace/src/dalibo/temboard/.venv/bin/python3
cachedir: .pytest_cache
postgresql: 17 (/usr/lib/postgresql/17/bin)
flask: 3.1.2
sqlalchemy: 1.4.54
system: Debian GNU/Linux 13 (trixie)
tornado: 6.4.2
bottle: 0.13.4
cryptography: 46.0.3
libpq: 17.6
psycopg2: 2.9.11 (dt dec pq3 ext lo64)
temboard: 9.0.1 (/home/bersace/src/dalibo/temboard/.venv/bin/temboard)
temboard-agent: 9.0.1 (/home/bersace/src/dalibo/temboard/.venv/bin/temboard-agent)
rootdir: /home/bersace/src/dalibo/temboard/tests
...
tests/test_00_setup_ui.py::test_temboard_version PASSED                  [ 12%]
...
tests/test_20_register.py::test_web_register PASSED                      [100%]

============================== 8 passed in 17.69s ==============================
$

pytest tests/ --help describes custom options --pg-version and --selenium. Take care of the custom pytest report header, it shows which temboard and temboard-agent binary is used, the bin directory of PostgreSQL and more.

pytest tests/ --fixtures describes fixtures defined by tests/conftest.py. Fixtures configure a postgres for monitoring, an agent and the UI in workdir/ prefix. This may help you write a new test.

Selenium standalone container runs a headless Xvfb server with noVNC enabled. View live tests in your browser at http://localhost:7900/ . Click the connect button and interract with the tested UI using the embedded Firefox.

Selenium container may be flaky. If you suspend your computer, you may have timeout from selenium. Use make restart-selenium to workaround this.

UI Database Schema Version

temBoard database is versionned. A version is the name of a file in temboardui/model/versions. Each file contains the code to execute to upgrade to this version.

To create a new version, put a new file in temboardui/model/versions/ prefixed with a discrete number following the last version. As of now, version file must ends with .sql and contains valid PostgreSQL SQL.

That’s all. Use temboard migratedb to check and upgrade temBoard repository.

Building CSS and Javascript

temBoard UI mainly relies on Bootstrap. The CSS files are compiled with SASS. ViteJS manages assets from ui/temboardui/static/src. ViteJS builds assets in ui/temboardui/static directory.

Execute all the following commands in ui/ directory.

In case you want to contribute on the styles, first install the NodeJS dev dependencies:

$ npm install

Then you can either build a dist version of the CSS:

$ npm run build

Or run dev server which watch changes on source files and hot-reload modules in your browser:

$ npm run dev

Now restart temBoard UI configured with ViteJS dev server base URL from environment variable VITEJS:

Warning

You must execute temBoard at top level directory, not in ui/ directory.

$ VITEJS=http://localhost:5173 uv run temboard --debug
...
2022-08-23 10:40:57 CEST temboardui[2315935] DEBUG:  vitejs: Using ViteJS dev server at http://localhost:5173.
2022-08-23 10:40:57 CEST temboardui[2315935] DEBUG:  vitejs: Skip reading ViteJS manifest.
...

Beware of CORS! Depending on your browser product and version, you may hit an unstyled page if CORS policy denies loading assets from ViteJS dev server. Ensure you run temBoard in plain HTTP and that you access both temBoard and ViteJS dev server on localhost.

All assets managed by ViteJS are hot reloaded, including CSS. ViteJS Hot reload does not required reloading server-side.

Editing Documentation

The documentation is written in Markdown and built with mkdocs.

$ uv run mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - alerting.md
              - postgres_upgrade.md
INFO     -  Documentation built in 0.42 seconds
INFO     -  [16:21:24] Serving on http://127.0.0.1:8000/
...

Go to http://127.0.0.1:8000/ to view the documentation. mkdocs has hot reload: saving file triggers a refresh in your browser.

Try to use semantic line breaks: split lines by idea instead of reflowing words. This helps reading diff, handling conflicts when rebasing.

Building Packages

Building packages for RHEL, Debian and compatible clones requires Docker and Docker Compose for isolation. UI and agent each have packaging/nfpm/ directory with a Makefile and scripts to build DEB and RPM packages.

The builder script searches for wheels in respective dist/. Use top level make dist to generate wheels.

RPM Packages

Use build-rhel<version> make target like this:

make -C ui/packaging/nfpm/ build-rhel9

Version can be either 10, 9 or 8. agent/packaging/nfpm/Makefile provides the same targets.

Uploading to Dalibo Labs YUM repository requires internal project yum-labs and access.

Building Debian Package

For signing changes, you need the devscripts package and a GPG private key. For uploading DEB, you require dput.

Define environment variables DEBFULLNAME and DEBEMAIL. mkchanges.sh scripts signs changes with your GPG key matching these environment variables.

Use build-<codename> target like this:

make -C ui/packaging/nfpm/ build-bullseye

codename is one of trixie, bookworm or bullseye for Debian and noble or jammy for Ubuntu. agent/packaging/nfpm/Makefile provides the same targets.

Testing with Grafana

temBoard exposes /metrics in OpenMetric format. Development environment includes Prometheus and Grafana preconfigured with authenticated access and file-based service discovery. You only need a couple of steps to view temBoard metrics in Grafana.

  • Start development temBoard UI and at lease one of agent0 or agent1.
  • Generate Prometheus targets using make prom-targets.
  • Go to development Grafana import page.
  • Import Dashboard ID 1860 (Node Exporter Full) or 9628 (PostgreSQL Database).
  • Now wait a few minutes that Prometheus scrapes data. Scrape interval is 1 minute.

temBoard exposes only a subset of metrics from node_exporter and postgres_exporter, plus a set of custom metrics prefixed with x, e.g. xpg_wal_files_bytes_total. Thus a lot of panel will show N/A.

Prometheus also watch dev/prometheus/targets/custom.yaml files for hand written targets.

Investigate logs with lnav

[lnav] is an awesome tool to browse and analyze log files. temBoard provides configuration for lnav to enhance experience. make develop configures lnav for better analysis of PostgreSQL and temBoard logs. Just run lnav on temBoard logs and you’re good to go.

$ temboard |& lnav

Releasing

Releasing a new version of temBoard requires write access to master branch on main repository and Dalibo Labs YUM and APT repositories.

To release a new version:

  • Checkout release branch : master or v8.
  • Edit ui/pyproject.toml and agent/pyproject.toml without committing. The version must be the same and follow PEP440.
  • Check, commit, tag and push using make release.

For stable release, you need write access to Dalibo Labs repositories:

  • Wait for CircleCI pipeline to publish GitHub releases.
  • Download packages with make download-packages.
  • Publish Debian and RPM packages with make publish-packages.

To release a v8 minor version, please follow v8 documentation.

Don’t forget to update Compatibility Guide.

Throw Environment

make clean destroy virtual environments and docker services. Restart from make develop as documented above. If you only need to trash services, use docker compose as usual : docker compose down -v, running make develop will restart them and configure the database.