From 38cd889f7b24a91bc6399e1eaf432b7146438c84 Mon Sep 17 00:00:00 2001
From: Martijn de Boer <github@sexybiggetje.nl>
Date: Thu, 13 Jun 2024 15:09:51 +0200
Subject: [PATCH] [docs] Add optional instructions for replicating SQLite for
 disaster recovery (#2981)

* Add optional instructions for replicating SQLite for disaster recovery

* Remove references to MacOS from replicating-sqlite.md

Resolve comment on review

* Add mention for replicating SQLite in database_maintenance.md

Adds a reference to the replicating sqlite page under database maintenance
---
 docs/admin/database_maintenance.md  |   4 ++
 docs/advanced/index.md              |   1 +
 docs/advanced/replicating-sqlite.md | 104 ++++++++++++++++++++++++++++
 mkdocs.yml                          |   1 +
 4 files changed, 110 insertions(+)
 create mode 100644 docs/advanced/replicating-sqlite.md

diff --git a/docs/admin/database_maintenance.md b/docs/admin/database_maintenance.md
index eedf6d1b7..e937e7777 100644
--- a/docs/admin/database_maintenance.md
+++ b/docs/admin/database_maintenance.md
@@ -46,6 +46,10 @@ The basic steps are:
 2. While connected to your GoToSocial database file in the `sqlite3` shell, run `VACUUM;` (this may take quite a few minutes).
 3. Start GoToSocial.
 
+### Replication
+
+It's a common practice to set up safeguards for your database like replication. SQLite can be replicated using external software. The basic steps are described on the [Replicating SQLite](../advanced/replicating-sqlite.md) page.
+
 ## Postgres
 
 TODO: Maintenance recommendations for Postgres. 
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
index 81773801f..196c2b959 100644
--- a/docs/advanced/index.md
+++ b/docs/advanced/index.md
@@ -15,3 +15,4 @@ We consider these topics advanced because applying them incorrectly does have th
 * [Firewall configuration](security/firewall.md)
 * [Tracing](tracing.md)
 * [Metrics](metrics.md)
+* [Replicating SQLite](replicating-sqlite.md)
diff --git a/docs/advanced/replicating-sqlite.md b/docs/advanced/replicating-sqlite.md
new file mode 100644
index 000000000..7de5f19a5
--- /dev/null
+++ b/docs/advanced/replicating-sqlite.md
@@ -0,0 +1,104 @@
+# Replicating SQLite
+
+Next to your regular [backup methods](../admin/backup_and_restore.md), you might want to set up replication for disaster recovery to another path or external host.
+
+For this to work properly, SQLite needs the journal mode to be configured in `WAL` mode, with synchronous mode set to `NORMAL`. This is the default configuration for GoToSocial.
+
+You can check your settings in the configuration file. The journal mode is set in `db-sqlite-journal-mode` and the synchronous mode in `db-sqlite-synchronous`.
+
+## Litestream on Linux
+
+A relatively light, and fast way to set up replication with SQLite is by using [Litestream](https://litestream.io). It can be configured very easily and supports different backends like file based replication, S3 compatible storage and many other setups.
+
+You can then install the prebuilt package by either the deb file on Linux, or building it from source on other distributions.
+
+Using a .deb package on Linux:
+
+Navigate to the [releases page](https://github.com/benbjohnson/litestream/releases/latest), and download the latest release (make sure to select the appropiate platform for the wget command below).
+
+
+```bash
+wget https://github.com/benbjohnson/litestream/releases/download/v0.3.13/litestream-v0.3.13-linux-amd64.deb
+sudo dpkg -i litestream-*.deb
+```
+
+## Configuring Litestream
+
+Configuration is done by editing the configuration file. It's located in /etc/litestream.yml.
+
+### Configuring file based replication
+
+```yaml
+dbs:
+    - path: /gotosocial/sqlite.db
+      - path: /backup/sqlite.db
+```
+
+### Configuring S3 based replication
+
+Set up a bucket for replication, and make sure to set it to be private.
+Make sure to replace the example `access-key-id` and `secret-access-key` with the proper values from your dashboard.
+
+```yaml
+access-key-id: AKIAJSIE27KKMHXI3BJQ
+secret-access-key: 5bEYu26084qjSFyclM/f2pz4gviSfoOg+mFwBH39
+
+dbs:
+    - path: /gotosocial/sqlite.db
+      - url: s3://my.bucket.com/db
+
+```
+
+When using a S3 compatible storage provider you will need to set an endpoint.
+For example for minio this can be done with the following configuration.
+
+```yaml
+access-key-id: miniouser
+secret-access-key: miniopassword
+
+dbs:
+    - path: /gotosocial/sqlite.db
+      - type: s3
+	    bucket: mybucket
+		path: sqlite.db
+		endpoint: minio:9000
+```
+
+## Enabling replication
+
+You can enable replication on Linux by enabling the Litestream service.
+
+```bash
+sudo systemctl enable litestream
+sudo systemctl start litestream
+```
+
+Check if it's running properly using `sudo journalctl -u litestream -f`.
+
+If you need to change the configuration file, restart Litestream:
+
+```bash
+sudo systemctl restart litestream
+```
+
+### Recovering from the configured backend
+
+You can pull down a recovery file from the stored backend with the following simple command.
+
+```bash
+sudo litestream restore
+```
+
+If you have configured multiple files to be backupped, or have multiple replicas, specify what you want to do.
+
+For filebased replication:
+
+```bash
+sudo litestream restore -o /gotosocial/sqlite.db /backup/sqlite.db
+```
+
+For s3 based replication:
+
+```bash
+sudo litestream restore -o /gotosocial/sqlite.db s3://bucketname/db
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index a9dbf68cb..6b79a3d1a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -113,6 +113,7 @@ nav:
     - "advanced/healthchecks.md"
     - "advanced/tracing.md"
     - "advanced/metrics.md"
+    - "advanced/replicating-sqlite.md"
 
   - "Admin":
       - "admin/settings.md"