[docs] Don't run SQLite on networked storage (#3369)

* [docs] Don't run SQLite on networked storage

This updates our documentation to include warnings against running
SQLite on networked storage.

It also slightly reorganises and consolidates some admonitions on the
Getting Started page because it was getting a bit too busy with repeated
information.

* [docs] Reword a few things

docs/advanced/index.md

@@ -16,3 +16,4 @@ We consider these topics advanced because applying them incorrectly does have th
 * [Tracing](tracing.md)
 * [Metrics](metrics.md)
 * [Replicating SQLite](replicating-sqlite.md)
+* [SQLite on networked storage](sqlite-networked-storage.md)

docs/advanced/sqlite-networked-storage.md

@@ -0,0 +1,35 @@
+# SQLite on networked storage
+
+SQLite's operating model assumes the database and the processes or applications using it are colocated on the same host. When running the database in WAL-mode, which is GoToSocial's default, it relies on shared memory between processes to ensure the integrity of your database.
+
+!!! quote
+    All processes using a database must be on the same host computer; WAL does not work over a network filesystem. This is because WAL requires all processes to share a small amount of memory and processes on separate host machines obviously cannot share memory with each other. 
+
+    — SQLite.org [Write-Ahead Logging](https://www.sqlite.org/wal.html)
+
+This also means that any other processes accessing the database need to run in the same namespace or container context.
+
+It is in theory possible to run SQLite over Samba, NFS, iSCSI or other forms of filesystems accessed over the network. But it is neither recommended nor supported by the SQLite maintainers, irrespective of whether you're running with write-ahead logging or not. Doing so puts you at risk of database corruption. There is a long history of networked storage having synchronisation issues in their locking primitives, or implementing them with weaker guarantees than what a local filesystem can provide.
+
+Your cloud provider's external volumes, like Hetzner Cloud Volumes, AWS EBS, GCP Persistent Disk etc. may also cause problems, and add variable latency. This has a tendency to severely degrade SQLite's performance.
+
+If you're going to access your database over the network, it's better to use a database with a client-server architecture. GoToSocial supports Postgres for such use-cases.
+
+For the purpose of having a copy of the SQLite database on durable long-term storage, refer to [SQLite streaming replication](replicating-sqlite.md) instead. Remember that neither replication nor using a networked filesystem are a substitute [for having backups](../admin/backup_and_restore.md).
+
+## Settings
+
+!!! danger "Corrupted database"
+    We do not support running GoToSocial with SQLite on a networked filesystem and we will not be able to help you if you damage your database this way.
+
+Should you really want to take this risk, you'll need to adjust the SQLite [synchronous][sqlite-sync] mode and [journal][sqlite-journal] mode to match the limitations of the filesystem.
+
+[sqlite-sync]: https://www.sqlite.org/pragma.html#pragma_synchronous
+[sqlite-journal]: https://www.sqlite.org/pragma.html#pragma_journal_mode
+
+You'll need to update the following settings:
+
+* `db-sqlite-journal-mode`
+* `db-sqlite-synchronous`
+
+We don't provide any recommendations as this will vary based on the solution you're using. See [this issue](https://github.com/superseriousbusiness/gotosocial/issues/3360#issuecomment-2380332027) for what you could potentially set those values to.

docs/getting_started/index.md

@@ -65,14 +65,16 @@ If you decide to use a VPS instead, you can spin yourself up something cheap wit
 
 [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.
 
+!!! warning "Cloud storage volumes"
+    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.
+    
+    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. This will result in your GoToSocial instance performing poorly.
+
 !!! 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
 
 Please make sure to check on your distribution system requirments, especially memory. Many distributions have baseline requirements and running them on a system that doesn't meet them will cause problems without further tuning and tweaking on your part.
@@ -99,13 +101,15 @@ GoToSocial supports both SQLite and Postgres as database drivers. Though it is p
 
 SQLite is the default driver and it's been shown to work brilliantly for instances in the range of 1-30 users (or maybe more).
 
+!!! danger "SQLite on networked storage"
+    Don't put your SQLite database on remote storage, whether that's NFS/Samba, iSCSI volumes, things like Ceph/Gluster or your cloud provider's network volume storage solution.
+
+    See [SQLite on networked storage](../advanced/sqlite-networked-storage.md) for further information.
+
 If you're planning on hosting more people than this on an instance, you may wish to use Postgres instead, as it offers the possibility of database clustering and redundancy, at the cost of some complexity.
 
 Regardless of which database driver you choose, for proper performance 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 "Cloud Storage Volumes"
-    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.
-
 !!! tip
     Please [backup your database](../admin/backup_and_restore.md). The database contains encryption keys for the instance and any user accounts. You won't be able to federate again from the same domain if you lose these keys!
 

mkdocs.yml

@@ -116,6 +116,7 @@ nav:
     - "advanced/tracing.md"
     - "advanced/metrics.md"
     - "advanced/replicating-sqlite.md"
+    - "advanced/sqlite-networked-storage.md"
 
   - "Admin":
       - "admin/settings.md"