diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1d59c05
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# srv
+## principles
+* strong security
+   * fine-grained user-based access and security
+   * rootless docker
+   * user-space systemctl for scheduled tasks
+* re-runnable and idempotent; changes to configuration does the same work as initial setup without losing state
+
+## observable outputs
+* given gitea domain `<git_url>`:
+   * configures ssl for `https://<git_url>`
+   * forwards `http://<git_url>` -> `https://<git_url>`
+   * `https://<git_url>` serves gitea instance using sqlite3
+   * SSH git authentication via `git@<git_url>` is fully supported
+   * gitea has actions enabled and a runner instance provided
+   * any gitea instance data and sessions are preserved (_Note: the linux user that "owns" the gitea instance was deleted and recreated, and configuration was overwritten by `src/gitea-app.ini`._)
+
+## setup
+copy `src/gitea-app.ini.sample` to `src/gitea-app.ini` and fill in the `; <snip>` secrets
+
+## running
+copy this repository to the debian image, ex with sshfs:
+```sh
+> mkdir ./ext
+> sshfs user@host:/mnt ./ext
+> rm ./ext/*; cp ./src/* ./ext/ # <- effectively deploys new configuration
+```
+
+then on the host run `/mnt/000-entry.sh` in an interactive shell.