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 Poetry to configure an environment development, build the project, and push wheel/sdist to PyPI.

  1. First, install Poetry, following this guide: Poetry installation.
  2. Now Poetry should be available in your command line. Check that the following command is displaying Poetry version:
poetry --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 Poetry:
cd dnsrobocert
poetry env use python3
  1. Activate the virtual environment:
  • For Linux/Mac OS X:
source .venv/bin/activate
  • For Windows (using Powershell):
.\.venv\Scripts\activate
  1. Install development dependencies.
poetry install

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 ;)