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 ofCertbot andLexicon. Here are the repartition of the roles:

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

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

  • DNSroboCert

    • holds and validates the central configuration for users,

    • couplesCertbot andLexicon through the auth/cleanup hook system ofCertbot’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 theCertbot renewal process.

Setting up a development environment

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

  1. First, installUV, 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 upstreamGitHub 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 withthe OS Python packages installed globally.

  1. Setup the virtual environment for DNSroboCert using UV:

cd dnsrobocertuv 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) usingPytest.

  • The code is formatted usingBlack andIsort to keep as possible unified and standardized writing conventions.

  • The code is linted withFlake8 and statically checked usingMyPy.

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 utilsmypy src

  1. Reformat your code:

isort -rc src test utilsblack src test utils

Submitting a PR

Well, you know what to do ;)