docs: organise documentation
This commit is contained in:
@@ -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 🔪)
|
- [setup](docs/setup.md)
|
||||||
2. create a new admin user
|
- [caddy](docs/services/caddy.md)
|
||||||
- `sudo useradd -m -G wheel admin`
|
- [stalwart](docs/services/stalwart.md)
|
||||||
- `sudo passwd admin`
|
- [bulwark](docs/services/bulwark.md)
|
||||||
- `sudo su - admin`
|
- [gitea](docs/services/gitea.md)
|
||||||
3. use the system setup script, and log out
|
- [backups](docs/backups.md)
|
||||||
- `sudo dnf install git -y`
|
- [misc](docs/misc.md)
|
||||||
- `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` | `@` | `<ip>` | apex domain |
|
|
||||||
| `A` | `post` | `<ip>` | mailserver |
|
|
||||||
| `A` | `mail` | `<ip>` | webmail |
|
|
||||||
| `A` | `git` | `<ip>` | gitea |
|
|
||||||
| `CAA` | `@` | `0 issue "letsencrypt.org"` | allow caddy to issue certs |
|
|
||||||
| `MX` | `@` | `post.atom.town.` / `10` | mail record |
|
|
||||||
|
|
||||||
### caddy
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> **todo** // detail setup
|
|
||||||
|
|
||||||
### stalwart
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>initial setup</summary>
|
|
||||||
|
|
||||||
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`
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>further setup</summary>
|
|
||||||
|
|
||||||
- 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: `<generate_secret>`
|
|
||||||
- redirect uris: `https://git.atom.town/user/oauth2/Stalwart/callback`
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>useful links</summary>
|
|
||||||
|
|
||||||
- https://stalw.art/docs
|
|
||||||
- https://testconnectivity.microsoft.com/tests/Imap/input
|
|
||||||
- https://mail-tester.com
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### bulwark
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> **todo** // detail setup
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>useful links</summary>
|
|
||||||
|
|
||||||
- https://bulwarkmail.org/docs
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### gitea
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>initial setup</summary>
|
|
||||||
|
|
||||||
- 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" <system@atom.town>`
|
|
||||||
- smtp username: `system@atom.town`
|
|
||||||
- smtp password: `<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`
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>further setup</summary>
|
|
||||||
|
|
||||||
- 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: `<secret_from_stalwart>`
|
|
||||||
- openid connect auto discovery url: `https://post.atom.town/.well-known/openid-configuration`
|
|
||||||
</details>
|
|
||||||
|
|
||||||
## 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 <service> env`
|
|
||||||
|
|||||||
@@ -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/`
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
## misc
|
||||||
|
|
||||||
|
**useful commands**
|
||||||
|
|
||||||
|
- `docker exec <service> env`
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
### bulwark
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **todo** // detail setup
|
||||||
|
|
||||||
|
**useful links**
|
||||||
|
|
||||||
|
- https://bulwarkmail.org/docs
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
### caddy
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **todo** // detail setup
|
||||||
@@ -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" <system@atom.town>`
|
||||||
|
- smtp username: `system@atom.town`
|
||||||
|
- smtp password: `<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`
|
||||||
|
</details>
|
||||||
|
|
||||||
|
**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: `<secret_from_stalwart>`
|
||||||
|
- openid connect auto discovery url: `https://post.atom.town/.well-known/openid-configuration`
|
||||||
@@ -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: `<generate_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
|
||||||
|
</details>
|
||||||
@@ -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` | `@` | `<ip>` | apex domain |
|
||||||
|
| `A` | `post` | `<ip>` | mailserver |
|
||||||
|
| `A` | `mail` | `<ip>` | webmail |
|
||||||
|
| `A` | `git` | `<ip>` | gitea |
|
||||||
|
| `CAA` | `@` | `0 issue "letsencrypt.org"` | allow caddy to issue certs |
|
||||||
|
| `MX` | `@` | `post.atom.town.` / `10` | mail record |
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user