From a243378486f9dc3d2f8a150ff5eae7338b8e5d67 Mon Sep 17 00:00:00 2001
From: futile <git@futile.eu>
Date: Fri, 17 Jul 2026 20:41:54 +0100
Subject: [PATCH] update readme

---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 66 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 41bb9d7..ccc1292 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,78 @@
+# thingy!
+
+some kind of hosting setup
+
+## setup
+
+1. log into vps (make sure it's fedora)
+2. we need git `sudo dnf install git -y`
+3. clone this `git clone https://gitlab.com/futile/thingy`
+4. cd in `cd thingy`
+5. make set up script executable `chmod +x set-up-system.sh`, & run it `./set-up-system.sh`
+6. log out and back in `exit`, `ssh whatever@whatever`...
+7. cd again `cd thingy`
+8. populate a .env `micro .env`
+9. finally, start everything `docker compose up`
+10. continue with service-specific setups .....
+
+## services
+
+specifics for everything
+
+**currently serving**
+- via docker
+  - **caddy** – http server & reverse proxy
+  - **stalwart** – mailserver
+  - **bulwark** – webmail
+- via caddy
+  - `m.yaoi.dog` – mail (server & admin dash)
+  - `mail.yaoi.dog` – mail (webmail)
+
+
 ### stalwart
 
 **first setup**
 - server identity
-  - server hostname: m.yaoi.dog
-  - default email domain: yaoi.dog
-  - automatically obtain tls certificate: true
-  - generate email signing keys: true
+  - server hostname: `m.yaoi.dog`
+  - default email domain: `yaoi.dog`
+  - automatically obtain tls certificate: `true`
+  - generate email signing keys: `true`
 - storage
-  - main data storage: sqlite
-  - path: /var/lib/stalwart/mail.sqlite
+  - main data storage: `rocksdb`
+  - path: `/var/lib/stalwart/`
 - account directory
-  - directory type: use internal
+  - directory type: `use internal`
 - logging
-  - log destination: console
+  - log destination: `console`
 - automatic dns management
-  - dns server type: porkbun
-  - api key
-  - secret key
-  - description: porkbun
+  - dns server type: `porkbun`
+  - description: `porkbun`
 
 **further setup**
 - settings -> security -> allowed ips
-  - added 172.18.0.0/24
+  - added `172.18.0.0/24`; reason: `internal`
 - settings -> network -> http -> security
-  - permissive cors policy: true
-- settings -> telemetry -> tracers
-  - tracer type: log file
-  - path: /var/log/stalwart
+  - permissive cors policy: `true`   **[restart needed]**
+
+**notes**
+- in [docker-compose.yml](docker-compose.yml), a `stalwart-logs` volume is currently defined but not being used, due to the fact that stalwart does not seem to create anything within it. i need to figure out why. for now, stalwart logs to console.
+
+**useful links**
+- https://stalw.art/docs/install/platform/docker/
+- https://stalw.art/docs/install/security/
+- https://stalw.art/docs/server/reverse-proxy/caddy/
+- https://stalw.art/docs/telemetry/tracing/log/
+- https://testconnectivity.microsoft.com/tests/Imap/input
+- https://mail-tester.com/
+
+### bulwark
+
+**useful links**
+- https://bulwarkmail.org/docs/deployment/docker
+- https://bulwarkmail.org/docs/guides/admin
+- https://bulwarkmail.org/docs/getting-started/configuration/environment-reference
+
+### caddy
+
+**notes**
+- caddy will not be able to issue certificates if stalwart creates the CAA record, you should create one yourself like so: `CAA` `@` `0 issue "letsencrypt.org"`