Add READMEHEADmaster

This gives a brief introduction to the goals of the project, and outlines the
config file format.

1 files changed, 69 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6160198
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+<!--
+SPDX-FileCopyrightText: 2024 Matthew Fennell <matthew@fennell.dev>
+
+SPDX-License-Identifier: AGPL-3.0-only
+-->
+
+# Automatic certificate renewal
+
+This project is a wrapper around [LEGO](https://go-acme.github.io/lego/). Given
+a toml config file with various information about domains, it invokes lego to
+renew the certificates automatically.
+
+We take care to reuse the account used to generate the request. This means that
+TLSA records will remain correct after renewal.
+
+## Config file
+
+Place a `config.toml` file in the current working directory.
+
+This file has a `[config]` section, and a section for each individual domain,
+e.g. `[domains.example-org]`. Apart from being under the `domain` section,
+domain headers do not have to be named in any particular way.
+
+Imagine you would like to deploy certificates to both a forgejo and prosody
+instance to `example.org`. Then, your config might look like this:
+
+```toml
+[config]
+
+acme_server = "https://acme-v02.api.letsencrypt.org/directory"
+timeout_seconds = 600
+
+[domains.example-org]
+
+acme_email = "user@example.org"
+desec_token = "3x4mPl3t0K3n"
+renew_days = 60
+
+domains = [
+  "example.org",
+  "anon.example.org",
+  "conference.example.org",
+  "turn.example.org",
+  "upload.example.org",
+  "webchat.example.org",
+]
+
+renew_script = "install-for ~/.ssh/id_rsa --prosody admin@chat.example.org --forgejo admin@example.org"
+```
+
+This will generate a single certificate for all of the given domains (with the
+first in the list being the "main" domain), and then use the provided ssh key
+and script to install the certificate for the given services, across the given
+hosts.
+
+## Git hooks
+
+We provide sample git hooks in the `hooks` directory. To use these, ensure the
+following packages are installed:
+
+* black
+* gitlint
+* mypy
+* reuse
+* shellcheck
+
+```shell
+$ git config core.hooksPath hooks
+```