Update top-level installation/configuration pages

1 files changed, 137 insertions, 0 deletions

diff --git a/configuration.md b/configuration.md
new file mode 100644
index 0000000..bfbcf2e
--- /dev/null
+++ b/configuration.md
@@ -0,0 +1,137 @@
+---
+title: Configuration
+---
+
+This document provides general information about the configuration process of
+sr.ht services.
+
+Similar to the installation process, configuring sr.ht services typically
+involves steps that are specific each service. That being said, they all share
+certain aspects which are described below. Be sure to take a look at each
+service's configuration page for more details:
+
+- [builds.sr.ht](/builds.sr.ht/configuration.md)
+- [dispatch.sr.ht](/dispatch.sr.ht/configuration.md)
+- [git.sr.ht](/git.sr.ht/configuration.md)
+- [hg.sr.ht](/hg.sr.ht/configuration.md)
+- [lists.sr.ht](/lists.sr.ht/configuration.md)
+- [man.sr.ht](/man.sr.ht/configuration.md)
+- [meta.sr.ht](/meta.sr.ht/configuration.md)
+- [paste.sr.ht](/paste.sr.ht/configuration.md)
+- [todo.sr.ht](/todo.sr.ht/configuration.md)
+
+# Prerequisites
+
+Before configuring any sr.ht service, ensure that you have the following
+services installed. Every sr.ht service makes use of them, so your deployment
+will likely not work as expected if they are missing.
+
+- [core.sr.ht][core] - Provides functionality used by all sr.ht services.
+
+    - For users installing from packages, this package is automatically pulled
+      in as a dependency.
+
+    - For users installing from source, this package must be built *first*.
+
+        <div class="alert alert-info">
+          <strong>Note:</strong> The dependencies in <code>setup.py</code> may
+          not be up-to-date. For an up-to-date list of dependencies, consult
+          the latest
+          <a href="https://git.sr.ht/~sircmpwn/sr.ht-apkbuilds/tree/master/sr.ht/py3-srht/APKBUILD"
+             class="alert-link">Alpine package</a>.
+        </div>
+
+- [meta.sr.ht][meta] - Performs various administrative tasks (e.g., storing
+  account details, handling logins, SSH and PGP key storage).
+
+[meta]: https://git.sr.ht/~sircmpwn/meta.sr.ht
+[core]: https://git.sr.ht/~sircmpwn/core.sr.ht
+
+# Files
+
+## `config.ini`
+
+sr.ht services all use a shared configuration file, located at
+`/etc/sr.ht/config.ini`. The specific options you will configure will depend on
+the subset of and configuration of sr.ht services you choose to run.
+
+Each service provides an example configuration file, called
+`config.example.ini`, in their source code repository. You should consult these
+when creating your unified `config.ini`. Additionally, you may refer to each
+service's configuration reference pages for a full list of configuration
+options:
+
+- [sr.ht](/sr.ht/configuration_reference.md)
+- [builds.sr.ht](/builds.sr.ht/configuration_reference.md)
+- [dispatch.sr.ht](/dispatch.sr.ht/configuration_reference.md)
+- [git.sr.ht](/git.sr.ht/configuration_reference.md)
+- [hg.sr.ht](/hg.sr.ht/configuration_reference.md)
+- [lists.sr.ht](/lists.sr.ht/configuration_reference.md)
+- [man.sr.ht](/man.sr.ht/configuration_reference.md)
+- [meta.sr.ht](/meta.sr.ht/configuration_reference.md)
+- [paste.sr.ht](/paste.sr.ht/configuration_reference.md)
+- [todo.sr.ht](/todo.sr.ht/configuration_reference.md)
+
+## Service Files
+
+Service files for daemons are pre-configured by their distribution packages.
+
+Thus, after setting up your `config.ini` appropriately, you may start them
+using your distribution's service manager (e.g., `service git.sr.ht start`).
+
+# Databases
+
+Each service requires its own database. It is recommended to give each service
+its own database login, with full permissions for its database so that it may
+manage its own schema migrations.
+
+Once you populate the `connection-string` field in your `config.ini`, you may
+use the `<module>-initdb` script to populate the schema and stamp the latest
+revision for migrations (e.g., `metasrht-initdb` to set up meta.sr.ht's
+database). Note that if you have not configured SSL for your PostgreSQL server,
+you may have to append `?sslmode=disable` to your connection string for some
+services to work.
+
+## Schema Upgrades
+
+We use [alembic](https://alembic.zzzcomputing.com/en/latest/) to manage schema
+migrations. We use custom scripts to automatically retrieve database
+credentials from your `config.ini`. If you have installed from distribution
+packages, set `[<service>] migrate-on-upgrade=yes` to have migrations
+automatically performed during normal service upgrades (e.g., `[meta.sr.ht]
+migrate-on-upgrade=yes`).
+
+Otherwise, you may use `srht-migrate <service> upgrade head` to run updates for
+core.sr.ht migrations, and `<service>-migrate upgrade head` to run
+service-specific upgrades. For example, to upgrade the database schema for
+git.sr.ht, run `srht-migrate git.sr.ht upgrade head`, then `gitsrht-migrate
+upgrade head`. Other alembic commands are available, use `gitsrht-migrate
+--help` for more information.
+
+# Upgrade Procedure
+
+1. Stop all services.
+2. Update and upgrade your packages (e.g. `apk update && apk upgrade`).
+3. Resume all services.
+
+If you have high availability requirements, the web services may be
+load-balanced to avoid an outage.
+
+Database migrations will be performed automatically during upgrades. We source
+your alembic config from your main `config.ini`, so there's no need to write an
+`alembic.ini` file.
+
+Run `srht-migrate <service> stamp head && <service>-migrate stamp head` once to
+tell alembic the schema is up-to-date (e.g. `srht-migrate man.sr.ht stamp head
+&& mansrht-migrate stamp head`).  Future upgrades will be managed automatically
+by the package, or if you're using the source code you can run `srht-migrate
+<service> upgrade head && <service>-migrate upgrade head` when you pull the
+latest version down.
+
+# Integrations
+
+Many sr.ht services are able to integrate with third-party tools, such as:
+
+- [Prometheus](https://prometheus.io/) for monitoring.
+- Any S3-compatible object storage (e.g., [Minio](https://min.io/),
+  [Ceph](https://ceph.io/)).