From 3c9eac23b4c13fd24356896aff7a7dafa6ef4f9a Mon Sep 17 00:00:00 2001 From: futile Date: Thu, 23 Jul 2026 11:46:52 +0100 Subject: [PATCH] docs: organise documentation --- README.md | 213 ++------------------------------------ docs/backups.md | 28 +++++ docs/misc.md | 5 + docs/services/bulwark.md | 8 ++ docs/services/caddy.md | 4 + docs/services/gitea.md | 39 +++++++ docs/services/stalwart.md | 47 +++++++++ docs/setup.md | 45 ++++++++ docs/todo.md | 10 ++ 9 files changed, 196 insertions(+), 203 deletions(-) create mode 100644 docs/backups.md create mode 100644 docs/misc.md create mode 100644 docs/services/bulwark.md create mode 100644 docs/services/caddy.md create mode 100644 docs/services/gitea.md create mode 100644 docs/services/stalwart.md create mode 100644 docs/setup.md create mode 100644 docs/todo.md diff --git a/README.md b/README.md index 3c5aee9..41d642a 100644 --- a/README.md +++ b/README.md @@ -1,206 +1,13 @@ -# atom.town! +# atom.town -some kind of hosting setup +here, you will be at home. -## setup +## directory -1. log into the vps, make sure it's fedora (or else 🔪) -2. create a new admin user - - `sudo useradd -m -G wheel admin` - - `sudo passwd admin` - - `sudo su - admin` -3. use the system setup script, and log out - - `sudo dnf install git -y` - - `git clone https://gitlab.com/futile/atom.town` - - `./atom.town/scripts/system-setup.sh` - - `exit` -4. log in again, populate the `.env` and start everything up - - `cd atom.town` - - `micro .env` - - `docker compose up` -5. continue with service-specific setups ..... - -## services - -specifics for everything - -**currently serving** - -- via docker - - **caddy** – http server & reverse proxy - - **stalwart** – mailserver - - **bulwark** – webmail - - **gitea** – git server -- via caddy - - `atom.town` - homepage - - `post.atom.town` – mailserver, mail admin, and oidc - - `mail.atom.town` – webmail - - `git.atom.town` – git - -**dns setup** - -| type | host | value | notes | -|-------|-----------|---------------------------- |----------------------------| -| `A` | `@` | `` | apex domain | -| `A` | `post` | `` | mailserver | -| `A` | `mail` | `` | webmail | -| `A` | `git` | `` | gitea | -| `CAA` | `@` | `0 issue "letsencrypt.org"` | allow caddy to issue certs | -| `MX` | `@` | `post.atom.town.` / `10` | mail record | - -### caddy - -> [!NOTE] -> **todo** // detail setup - -### stalwart - -
- initial setup - -1. server identity - - server hostname: `post.atom.town` - - default email domain: `atom.town` - - automatically obtain tls certificate: `true` - - generate email signing keys: `true` -2. storage - - main data storage: `rocksdb` - - path: `/var/lib/stalwart/` -3. account directory - - directory type: `use internal` -4. logging - - log destination: `console` -5. automatic dns management - - dns server type: `porkbun` - - description: `porkbun` -
- -
- further setup - -- settings -> security -> allowed ips - - added `172.18.0.0/16`; reason: `docker internal` -- settings -> network -> http -> security - - permissive cors policy: `true` **[restart needed]** -- settings -> authentication -> oidc provider - - oauth settings - - key: `secret read from environment variable` - - variable name: `OIDC_KEY` - - openid connect - - signature algorithm: `ECDSA using P-384 and SHA-384` - - signature key: `secret read from environment variable` - - variable name: `OIDC_SIGNATURE_KEY` -- management -> directory -> oauth clients - - create oauth client - - client id: `gitea` - - description: `Gitea` - - client secret: `` - - redirect uris: `https://git.atom.town/user/oauth2/Stalwart/callback` -
- -
- useful links - -- https://stalw.art/docs -- https://testconnectivity.microsoft.com/tests/Imap/input -- https://mail-tester.com -
- -### bulwark - -> [!NOTE] -> **todo** // detail setup - -
- useful links - -- https://bulwarkmail.org/docs -
- -### gitea - -
- initial setup - -- database settings - - database type: `sqlite3` - - path: `/data/gitea/gitea.db` -- general settings - - site title: `We cock. Dick. BALLING.` - - server domain: `git.atom.town` - - ssh server port: `22` - - gitea base url: `https://git.atom.town/` - - enable update checker: `true` -- email settings - - smtp host: `post.atom.town` - - smtp port: `465` - - send email as: `"Gitea" ` - - smtp username: `system@atom.town` - - smtp password: `` - - enable email notifications: `true` -- server and third-party service settings - - enable openid sign-in: `false` - - disable self-registration: `false` - - allow registration only through external services: `true` - - enable openid self-registration: `true` - - hidden email domain: `git.atom.town` - - password hash algorithm: `argon2` -
- -
- further setup - -- admin settings -> identity & access -> authentication sources - - add authentication source - - authentication type: `OAuth2` - - authentication name: `Stalwart` - - oauth2 provider: `OpenID Connect` - - client id (key): `gitea` - - client secret: `` - - openid connect auto discovery url: `https://post.atom.town/.well-known/openid-configuration` -
- -## backups - -backups are done with [vykar](https://vykar.borgbase.com) to [borgbase](https://borgbase.com) - -always remember to `docker compose stop` before doing any of this! - -**creating** - -- if on a new borgbase repo, run `vykar init` first -- to back up, run `sudo vykar backup` (sudo required as we are accessing `/var/lib/docker/volumes/`) -- to back up automatically, run `sudo EDITOR=micro crontab -e` and add the following: - ``` - TZ=UTC - 0 6 * * * /home/admin/atom.town/scripts/volume-backup.sh - ``` - -**restoring** - -the restore process is kind of fucked up but doable - -- restore on new system - - run `vykar list` to find a snapshot to use - - `sudo rm -rf /var/lib/docker/volumes/` - - then `sudo vykar restore abcd1234 /var/lib/docker/volumes/` - - figure out the UID:GID for all containers and `sudo chown -R UID:GID /var/lib/docker/volumes/.../_data/` their respective volumes -- restore on same system - - run `vykar list` to find a snapshot to use - - then `sudo vykar restore abcd1234 /var/lib/docker/volumes/` - -## todo - -- further secure the server (ratelimiting, hardening...) -- figure out best way to store .env, other credentials, and various secrets -- more services - - ~~gitea (need to change host ssh port)~~ - - vaultwarden -- ~~tie all services together with an sso~~ -- use postgres for everything - -## misc - -**useful commands** - -- `docker exec env` +- [setup](docs/setup.md) + - [caddy](docs/services/caddy.md) + - [stalwart](docs/services/stalwart.md) + - [bulwark](docs/services/bulwark.md) + - [gitea](docs/services/gitea.md) +- [backups](docs/backups.md) +- [misc](docs/misc.md) diff --git a/docs/backups.md b/docs/backups.md new file mode 100644 index 0000000..5765930 --- /dev/null +++ b/docs/backups.md @@ -0,0 +1,28 @@ +## backups + +backups are done with [vykar](https://vykar.borgbase.com) to [borgbase](https://borgbase.com) + +always remember to `docker compose stop` before doing any of this! + +**creating** + +- if on a new borgbase repo, run `vykar init` first +- to back up, run `sudo vykar backup` (sudo required as we are accessing `/var/lib/docker/volumes/`) +- to back up automatically, run `sudo EDITOR=micro crontab -e` and add the following: + ``` + TZ=UTC + 0 6 * * * /home/admin/atom.town/scripts/volume-backup.sh + ``` + +**restoring** + +the restore process is kind of fucked up but doable + +- restore on new system + - run `vykar list` to find a snapshot to use + - `sudo rm -rf /var/lib/docker/volumes/` + - then `sudo vykar restore abcd1234 /var/lib/docker/volumes/` + - figure out the UID:GID for all containers and `sudo chown -R UID:GID /var/lib/docker/volumes/.../_data/` their respective volumes +- restore on same system + - run `vykar list` to find a snapshot to use + - then `sudo vykar restore abcd1234 /var/lib/docker/volumes/` diff --git a/docs/misc.md b/docs/misc.md new file mode 100644 index 0000000..ef38bb7 --- /dev/null +++ b/docs/misc.md @@ -0,0 +1,5 @@ +## misc + +**useful commands** + +- `docker exec env` diff --git a/docs/services/bulwark.md b/docs/services/bulwark.md new file mode 100644 index 0000000..6d3fdcf --- /dev/null +++ b/docs/services/bulwark.md @@ -0,0 +1,8 @@ +### bulwark + +> [!NOTE] +> **todo** // detail setup + +**useful links** + +- https://bulwarkmail.org/docs diff --git a/docs/services/caddy.md b/docs/services/caddy.md new file mode 100644 index 0000000..387b2c8 --- /dev/null +++ b/docs/services/caddy.md @@ -0,0 +1,4 @@ +### caddy + +> [!NOTE] +> **todo** // detail setup diff --git a/docs/services/gitea.md b/docs/services/gitea.md new file mode 100644 index 0000000..1008df3 --- /dev/null +++ b/docs/services/gitea.md @@ -0,0 +1,39 @@ +### gitea + +**initial setup** + +- database settings + - database type: `sqlite3` + - path: `/data/gitea/gitea.db` +- general settings + - site title: `atom.town` + - server domain: `git.atom.town` + - ssh server port: `22` + - gitea base url: `https://git.atom.town/` + - enable update checker: `true` +- email settings + - smtp host: `post.atom.town` + - smtp port: `465` + - send email as: `"Gitea" ` + - smtp username: `system@atom.town` + - smtp password: `` + - enable email notifications: `true` +- server and third-party service settings + - enable openid sign-in: `false` + - disable self-registration: `false` + - allow registration only through external services: `true` + - enable openid self-registration: `true` + - hidden email domain: `git.atom.town` + - password hash algorithm: `argon2` + + +**further setup** + +- admin settings -> identity & access -> authentication sources + - add authentication source + - authentication type: `OAuth2` + - authentication name: `Stalwart` + - oauth2 provider: `OpenID Connect` + - client id (key): `gitea` + - client secret: `` + - openid connect auto discovery url: `https://post.atom.town/.well-known/openid-configuration` diff --git a/docs/services/stalwart.md b/docs/services/stalwart.md new file mode 100644 index 0000000..8c08004 --- /dev/null +++ b/docs/services/stalwart.md @@ -0,0 +1,47 @@ +### stalwart + +**initial setup** + +1. server identity + - server hostname: `post.atom.town` + - default email domain: `atom.town` + - automatically obtain tls certificate: `true` + - generate email signing keys: `true` +2. storage + - main data storage: `rocksdb` + - path: `/var/lib/stalwart/` +3. account directory + - directory type: `use internal` +4. logging + - log destination: `console` +5. automatic dns management + - dns server type: `porkbun` + - description: `porkbun` + +**further setup** + +- settings -> security -> allowed ips + - added `172.18.0.0/16`; reason: `docker internal` +- settings -> network -> http -> security + - permissive cors policy: `true` **[restart needed]** +- settings -> authentication -> oidc provider + - oauth settings + - key: `secret read from environment variable` + - variable name: `OIDC_KEY` + - openid connect + - signature algorithm: `ECDSA using P-384 and SHA-384` + - signature key: `secret read from environment variable` + - variable name: `OIDC_SIGNATURE_KEY` +- management -> directory -> oauth clients + - create oauth client + - client id: `gitea` + - description: `Gitea` + - client secret: `` + - redirect uris: `https://git.atom.town/user/oauth2/Stalwart/callback` + +**useful links** + +- https://stalw.art/docs +- https://testconnectivity.microsoft.com/tests/Imap/input +- https://mail-tester.com + diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..6c1f38e --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,45 @@ +## setup + +1. log into the vps, make sure it's fedora (or else 🔪) +2. create a new admin user + - `sudo useradd -m -G wheel admin` + - `sudo passwd admin` + - `sudo su - admin` +3. use the system setup script, and log out + - `sudo dnf install git -y` + - `git clone https://git.atom.town/atom/town` + - `./atom.town/scripts/system-setup.sh` + - `exit` +4. log in again, populate the `.env` and start everything up + - `cd atom.town` + - `micro .env` + - `docker compose up` +5. continue with service-specific setups ..... + +## services + +specifics for everything + +**currently serving** + +- via docker + - **caddy** – http server & reverse proxy + - **stalwart** – mailserver + - **bulwark** – webmail + - **gitea** – git server +- via caddy + - `atom.town` - homepage + - `post.atom.town` – mailserver, mail admin, and oidc + - `mail.atom.town` – webmail + - `git.atom.town` – git + +**dns setup** + +| type | host | value | notes | +|-------|-----------|---------------------------- |----------------------------| +| `A` | `@` | `` | apex domain | +| `A` | `post` | `` | mailserver | +| `A` | `mail` | `` | webmail | +| `A` | `git` | `` | gitea | +| `CAA` | `@` | `0 issue "letsencrypt.org"` | allow caddy to issue certs | +| `MX` | `@` | `post.atom.town.` / `10` | mail record | diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000..f0147ae --- /dev/null +++ b/docs/todo.md @@ -0,0 +1,10 @@ +## todo + +- write terms of service & privacy policy +- further secure the server (ratelimiting, hardening...) +- ~~figure out best way to store .env, other credentials, and various secrets~~ +- more services + - ~~gitea (need to change host ssh port)~~ + - vaultwarden +- ~~tie all services together with an sso~~ +- use postgres for everything