Metadata-Version: 2.4
Name: dnacme
Version: 0.1.1
Summary: DevNomads ACME DNS-01 hook for dehydrated and other ACME clients
Author-email: DevNomads <support@devnomads.nl>
License: MIT
Keywords: acme,dns-01,dehydrated,letsencrypt,devnomads
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Dynamic: license-file

# dnacme

Get free Let's Encrypt TLS certificates for domains you host at
[DevNomads](https://devnomads.nl) - including wildcard certificates like
`*.example.com`.

To issue a certificate, Let's Encrypt first asks you to prove you control
the domain. The DNS way to prove it is to add a special TXT record, let
Let's Encrypt check it, then remove it. `dnacme` does that for you: it adds
and removes the record through the DevNomads API automatically, so your
certificate tool can renew certificates unattended.

`dnacme` is a hook script. Your ACME client calls it to add the record
before the check and remove it afterwards. It speaks the simple hook
interface used by
[dehydrated](https://github.com/dehydrated-io/dehydrated), a small, popular
Let's Encrypt client, so it can be used with dehydrated or with any other
client that calls a hook the same way.

## Install

```sh
pip install dnacme
```

Or, to install it as a standalone command without touching your system
Python (recommended on servers and workstations):

```sh
uv tool install dnacme      # or: pipx install dnacme
```

Either way you get a `dnacme` command on your `PATH`.

## 1. Add your API key

Create an API key in the
[DevNomads portal](https://portal.devnomads.nl) under
**Profiel -> API Sleutels**.

The easiest way to store it is with the companion tool
[`dnctl`](https://pypi.org/project/dnctl/), which `dnacme` shares
credentials with:

```sh
pip install dnctl
dnctl configure        # paste your API key when asked
```

That's it - `dnacme` will find the key automatically.

Prefer not to install `dnctl`? You have two other options:

- Set an environment variable:

  ```sh
  export DN_API_KEY="your-devnomads-api-key"
  ```

- Or, for an unattended server, write the key to
  `/etc/dnacme/credentials`:

  ```ini
  [default]
  api_key = your-devnomads-api-key
  ```

## 2. Use it with dehydrated

Tell dehydrated to validate over DNS and to call `dnacme`. In your
`dehydrated/config` file:

```sh
CHALLENGETYPE="dns-01"
HOOK="dnacme"
```

Then request a certificate as usual:

```sh
dehydrated -c -d example.com -d '*.example.com'
```

dehydrated handles the rest, calling `dnacme` to add the record before the
check and remove it afterwards. The single `HOOK="dnacme"` line is all you
need; `dnacme` quietly ignores the other events dehydrated sends.

Issuing a certificate for both a domain and its wildcard at once is fully
supported: the two checks share one record, and `dnacme` keeps them from
interfering with each other.

## Test it by hand

You can add and remove a record yourself to check that your API key works.
The zone is detected automatically from the domains your key can manage:

```sh
dnacme set   example.com hello-world    # add the test record
dnacme unset example.com hello-world    # remove it again
```

If `set` prints a confirmation and `unset` removes it without errors, your
setup is ready.

## Troubleshooting

- **"no API key found"** - you haven't stored a key yet; see step 1.
- **"API rejected the key"** - the key is wrong, or it isn't allowed to
  edit this domain. Check it in the DevNomads portal.
- **"no DevNomads zone found"** - the domain isn't hosted at DevNomads, or
  this key can't see it.

## License

MIT - see [LICENSE](LICENSE). Use it freely.
