[docs] update deployment considerations docs with latest findings (#2821)

* [docs] update deployment considerations docs with latest findings

* simplify single-board computer section

docs/configuration/database.md

@@ -176,4 +176,13 @@ db-sqlite-cache-size: "8MiB"
 # Examples: ["0s", "1s", "30s", "1m", "5m"]
 # Default: "30m"
 db-sqlite-busy-timeout: "30m"
+
+cache:
+  # cache.memory-target sets a target limit that
+  # the application will try to keep it's caches
+  # within. This is based on estimated sizes of
+  # in-memory objects, and so NOT AT ALL EXACT.
+  # Examples: ["100MiB", "200MiB", "500MiB", "1GiB"]
+  # Default: "100MiB"
+  memory-target: "100MiB"
 ```

docs/getting_started/index.md

@@ -14,8 +14,8 @@ GoToSocial supports both SQLite and Postgres and you can start using either. We
 
 For databases to perform properly, they should be run on fast storage that operates with low and stable latency. It is possible to run databases on network attached storage, but this adds variable latency and network congestion to the mix, as well as potential I/O contention on the origin storage.
 
-!!! danger
+!!! danger "Cloud Storage Volumes"
-    The performance of Hetzner Cloud Volumes is not guaranteed and seems to have very volatile latency. You're going to have a bad time running your database on those with extremely poor query performance for even the most basic operations. Before filing performance issues against GoToSocial, make sure the problems reproduce with local storage.
+    Not all cloud VPS storage offerings are equal, and just because something claims to be backed by an SSD doesn't mean that it will necessarily be suitable to run a GoToSocial instance on. Please see the [Server/VPS section](#vps) section below.
 
 SQLite is great for a single-user instance. If you're planning on hosting multiple people it's advisable to use Postgres instead. You can always use Postgres regardless of the instance size.
 
@@ -30,21 +30,10 @@ You'll commonly see usernames existing at the apex of the domain, for example `@
 
 It is possible to have usernames like `@me@example.org` but have GoToSocial running on `social.example.org` instead. This is done by distinguishing between the API domain, called the "host", and the domain used for usernames, called the "account domain".
 
+If you intend to deploy your GoToSocial instance in this way, please read the [Split-domain deployments](../advanced/host-account-domain.md) document for details on how to do this.
+
 !!! danger
-    It's not possible to safely change whether the host and account domain are different after the fact. It requires regenerating the database and will cause confusion for any server you have already federated with.
+    It's not possible to safely change whether the host and account domain are different after the fact. It requires regenerating the database and will cause confusion for any server you have already federated with. Once your instance host and account domain are set, they're set.
-
-When using a single domain, you only need to configure the "host" in the GoToSocial configuration:
-
-```yaml
-host: "example.org"
-```
-
-When using a split domain approach, you need to configure both the "host" and the "account-domain":
-
-```yaml
-host: "social.example.org"
-account-domain: "example.org"
-```
 
 ## TLS
 
@@ -55,20 +44,46 @@ GoToSocial comes with built-in support for provisioning certificates through Let
 !!! tip
     Make sure you configure the use of modern versions of TLS, TLSv1.2 and higher, in order to keep communications between servers and clients safe. When GoToSocial handles TLS termination this is done automatically for you. If you have a reverse-proxy in use, use the [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/).
 
-## Server / VPS
+## Server / VPS System Requirements
 
-!!! bug "Clustering / multi-node deployments"
+!!! warning "Clustering / multi-node deployments"
     GoToSocial does not support [clustering or any form of multi-node deployment](https://github.com/superseriousbusiness/gotosocial/issues/1749). Though multiple GtS instances can use the same Postgres database and either shared local storage or the same object bucket, GtS relies on a lot of internal caching to keep things fast. There is no mechanism for synchronising these caches between instances. Without it, you'll get all kinds of odd and inconsistent behaviour.
 
-GoToSocial aims to fit in small spaces so we try and ensure that the system requirements are fairly minimal: for a single-user instance with about 100 followers/followees, it uses somewhere between 50 to 100MB of RAM. CPU usage is only intensive when handling media (encoding blurhashes, mostly) and/or doing a lot of federation requests at the same time.
+GoToSocial aims to fit in small spaces so we try and ensure that the system requirements are fairly minimal.
 
-These light requirements mean GtS runs pretty well on something like a Raspberry Pi (a €40 single-board computer). It's been tested on a Raspberry Pi Zero W as well (a €9 computer smaller than a credit card), but it's not quite able to run on that. It should run on a Raspberry Pi Zero W 2 (which costs €14!), but we haven't tested that yet. You can also repurpose an old laptop or desktop to run GoToSocial for you.
+### Memory
 
-If you decide to use a VPS instead, you can spin yourself up something cheap with Linux running on it. Most of the VPS offerings in the €2-€5 range will perform admirably for a personal GoToSocial instance.
+For a single-user instance with about 100-300 followers/followees, GoToSocial will likely hover consistently between 100MB to 250MB of RAM usage once the internal caches are hydrated.
+
+RAM usage may temporarily spike higher during periods of load (for example, when a status gets boosted by someone with many followers), so you should account for some overhead.
+
+512MB to 1GB of total RAM should be enough.
+
+In memory constrained environments, you can try setting `cache.memory-target` to a value lower than the default 100MB (see the database configuration options [here](../configuration/database.md#settings)).
+
+### CPU
+
+CPU usage is only intensive when handling media (encoding blurhashes, mostly) and/or handling a lot of federation requests at the same time. 1 decent CPU core should be fine.
+
+### Single-board Computers
+
+GoToSocial's light system requirements means that it runs pretty well on decently-specced single-board computers. If running on a single-board computer, you should ensure that GoToSocial is using a USB drive (preferably an SSD) to store its database files and media, not SD card storage, since the latter tends to be too slow to run a database on.
+
+### VPS
+
+If you decide to use a VPS instead, you can spin yourself up something cheap with Linux running on it. Most of the VPS offerings in the €2-€5 per month range will perform admirably for a personal GoToSocial instance.
 
 [Hostwinds](https://www.hostwinds.com/) is a good option here: it's cheap and they throw in a static IP address for free.
 
-[Greenhost](https://greenhost.net) is also great: it has zero CO2 emissions, but is a bit more costly.
+[Greenhost](https://greenhost.net) is also great: it has zero CO2 emissions, but is a bit more costly. Their 1GB, 1-cpu VPS works great for a single-user or small instance.
+
+!!! danger "Oracle Free Tier"
+    [Oracle Cloud Free Tier](https://www.oracle.com/cloud/free/) servers are not suitable for a GoToSocial deployment if you intend to federate with more than a handful of other instances and users.
+    
+    GoToSocial admins running on Oracle Cloud Free Tier have reported that their instances become extremely slow or unresponsive during periods of moderate load. This is most likely due to memory or storage latency, which causes even simple database queries to take a long time to run.
+
+!!! danger "Hetzner Cloud Volume"
+    The [performance of Hetzner Cloud Volumes](https://github.com/superseriousbusiness/gotosocial/issues/2471#issuecomment-1891098323) is not guaranteed and seems to have very volatile latency. You're going to have a bad time running your database on those, with extremely poor query performance for even the most basic operations. Before filing performance issues against GoToSocial, make sure the problems reproduce with local storage.
 
 ### Distribution system requirements
 
@@ -90,6 +105,22 @@ The BSD family of distributions don't document memory requirements as much, but
 [rhelreq]: https://access.redhat.com/articles/rhel-limits#minimum-required-memory-3
 [fedorareq]: https://docs.fedoraproject.org/en-US/fedora/latest/release-notes/welcome/Hardware_Overview/#hardware_overview-specs
 
+## Ports
+
+GoToSocial needs ports `80` and `443` open.
+
+* `80` is used for Lets Encrypt. As such, you don't need it if you don't use the built-in Lets Encrypt provisioning.
+* `443` is used to serve the API on with TLS and is what any instance you're federating with will try to connect to.
+
+If you can't leave `443` and `80` open on the machine, don't worry! You can configure these ports in GoToSocial, but you'll have to also configure port forwarding to properly forward traffic on `443` and `80` to whatever ports you choose.
+
+!!! tip
+    You should configure a firewall on your machine, as well as some protection against brute-force SSH login attempts and the like. Take a look at our [firewall documentation](../advanced/security/firewall.md) for pointers on what to configure and tools that can help you out.
+
+## Tuning
+
+Aside from the many instance tuning options present in the [example config file](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml) you can do additional tuning on the machine your GoToSocial instance is running on.
+
 ### Swap
 
 It is possible to run a system without swap. In order to safely do so and ensure consistent performance and service availability, you need to tune the kernel, system and your workloads accordingly. This requires a good understanding of your kernel's memory management system as well as the memory usage patterns of the workloads you're running.
@@ -102,9 +133,10 @@ Unless you're experienced in doing this kind of tuning and troubleshooting the i
 * less than 2GB of RAM: swap = RAM × 2
 * more than 2GB of RAM: swap = RAM, up to 8G
 
-Linux swaps pretty early. This tends to not be necessary on servers and in the case of databases can cause unnecessary latency. Though it's good to let your system swap if it needs to, it can help to tell it to be a little more conservative about how early it swaps. Configuring this on Linux is done by changing the `vm.swappiness` [sysctl][sysctl] value.
+!!! tip "Configuring Swappiness"
-
+    Linux swaps pretty early. This tends to not be necessary on servers and in the case of databases can cause unnecessary latency. Though it's good to let your system swap if it needs to, it can help to tell it to be a little more conservative about how early it swaps. Configuring this on Linux is done by changing the `vm.swappiness` [sysctl][sysctl] value.
-By default it's `60`. You can lower that to `10` for starters and keep an eye out. It's possible to run with even lower values, but it's likely unnecessary. To make the value persistent, you'll need to drop a configuration file in `/etc/sysctl.d/`.
+    
+    By default it's `60`. You can lower that to `10` for starters and keep an eye out. It's possible to run with even lower values, but it's likely unnecessary. To make the value persistent, you'll need to drop a configuration file in `/etc/sysctl.d/`.
 
 [sysctl]: https://man7.org/linux/man-pages/man8/sysctl.8.html
 
@@ -119,15 +151,3 @@ You can configure limits for a process using [systemd resource control settings]
 [openrccgv2]: https://wiki.gentoo.org/wiki/OpenRC/CGroups
 [libcg]: https://github.com/libcgroup/libcgroup/
 [cgv2mem]: https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files
-
-## Ports
-
-GoToSocial needs ports `80` and `443` open.
-
-* `80` is used for Lets Encrypt. As such, you don't need it if you don't use the built-in Lets Encrypt provisioning.
-* `443` is used to serve the API on with TLS and is what any instance you're federating with will try to connect to.
-
-If you can't leave `443` and `80` open on the machine, don't worry! You can configure these ports in GoToSocial, but you'll have to also configure port forwarding to properly forward traffic on `443` and `80` to whatever ports you choose.
-
-!!! tip
-    You should configure a firewall on your machine, as well as some protection against brute-force SSH login attempts and the like. Take a look at our [firewall documentation](../advanced/security/firewall.md) for pointers on what to configure and tools that can help you out.