Developer guide

Thanks a lot for your involvement. You will find here some tips to quickly setup a suitable development environment, and useful tools to ensure code quality in the project.

General design principles

DNSroboCert is coded entirely in Python, and uses features available starting with Python 3.6+.

It sits on top of Certbot and Lexicon. Here are the repartition of the roles:

  • Certbot takes care of the actual certificate issuances and renewals against the ACME CA server, in a compliant and secured processing that respects the RFC-8555 protocol,

  • Lexicon provides the central interface to communicate with the DNS API providers, and inserts the required TXT entries for the DNS-01 challenges,

  • DNSroboCert

    • holds and validates the central configuration for users,

    • couples Certbot and Lexicon through the auth/cleanup hook system of Certbot’s manual plugin, to issue/renew DNS-01 challenged based certificates,

    • orchestrates the post-deploy processing (autocmd, autorestart, files rights…),

    • executes a a cron job to trigger regularly the Certbot renewal process.

Setting up a development environment

DNSroboCert uses UV to manage the development environment & dependencies, build the project, and push wheel/sdist to PyPI.

  1. First, install UV, following this guide: UV installation.

  2. Now UV should be available in your command line. Check that the following command is displaying UV version:

uv --version

  1. Fork the upstream GitHub project and clone your fork locally:

git clone https://github.com/myfork/dnsrobocert.git

Note

A widely used development pattern in Python is to setup a virtual environment.
Python virtual environments allow to manage a dedicated and isolated Python runtime for a specific project.
It allows in particular to have a separated set of dependencies for the project that will not interfere with the OS Python packages installed globally.

  1. Setup the virtual environment for DNSroboCert using UV:

cd dnsrobocert
uv sync

  1. Activate the virtual environment:

  • For Linux/Mac OS X:

source .venv/bin/activate

  • For Windows (using Powershell):

.\.venv\Scripts\activate

At this point, you are ready to develop on the project. You can run the CLI that will use the local source code:

dnsrobocert --help

Code quality

The project DNSroboCert tries to follows the up-to-date recommended guideline in Python development:

  • DNSroboCert logic is tested with a pyramidal approach (unit tests + integration tests) using Pytest.

  • The code is formatted using Black and Isort to keep as possible unified and standardized writing conventions.

  • The code is linted with Flake8 and statically checked using MyPy.

Please ensure that your code is compliant with this guideline before submitting a PR:

  1. Ensure that tests are passing:

pytest test

Warning

On Windows you must run the tests from an account with administrative privileges to make them pass.

  1. Ensure that linting and static type checking are passing:

flake8 src test utils
mypy src

  1. Reformat your code:

isort -rc src test utils
black src test utils

Submitting a PR

Well, you know what to do ;)