From 73b760d82931d36896d9777337c3efc0fde67e04 Mon Sep 17 00:00:00 2001 From: Alex Vandiver Date: Tue, 7 May 2024 23:57:20 +0000 Subject: [PATCH] docs: Move warm-standby replication into postgresql.md. --- docs/production/deployment.md | 33 ++----------------------- docs/production/export-and-import.md | 4 +-- docs/production/postgresql.md | 29 ++++++++++++++++++++++ docs/production/requirements.md | 2 +- docs/production/system-configuration.md | 6 ++--- 5 files changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/production/deployment.md b/docs/production/deployment.md index 8cfa81f29e..7200b03b1d 100644 --- a/docs/production/deployment.md +++ b/docs/production/deployment.md @@ -206,8 +206,8 @@ the following after unpacking a Zulip production release tarball: ``` To run the database on a separate server, including a cloud provider's managed -PostgreSQL instance (e.g. AWS RDS), see out [dedicated PostgreSQL -documentation][postgresql]. +PostgreSQL instance (e.g. AWS RDS), or with a warm-standby replica for +reliability, see our [dedicated PostgreSQL documentation][postgresql]. [standalone.pp]: https://github.com/zulip/zulip/blob/main/puppet/zulip/manifests/profile/standalone.pp [zulipchat-puppet]: https://github.com/zulip/zulip/tree/main/puppet/kandra/manifests @@ -301,32 +301,3 @@ some other proxy, you can override this default by setting `S3_SKIP_PROXY = False` in `/etc/zulip/settings.py`. [s3]: upload-backends.md#s3-backend-configuration - -## PostgreSQL warm standby - -Zulip's configuration allows for [warm standby database -replicas][warm-standby] as a disaster recovery solution; see the -linked PostgreSQL documentation for details on this type of -deployment. Zulip's configuration builds on top of `wal-g`, our -[streaming database backup solution][wal-g], and thus requires that it -be configured for the primary and all secondary warm standby replicas. - -In addition to having `wal-g` backups configured, warm standby -replicas should configure the hostname of their primary replica, and -username to use for replication, in `/etc/zulip/zulip.conf`: - -```ini -[postgresql] -replication_user = replicator -replication_primary = hostname-of-primary.example.com -``` - -The `postgres` user on the replica will need to be able to -authenticate as the `replication_user` user, which may require further -configuration of `pg_hba.conf` and client certificates on the replica. -If you are using password authentication, you can set a -`postgresql_replication_password` secret in -`/etc/zulip/zulip-secrets.conf`. - -[warm-standby]: https://www.postgresql.org/docs/current/warm-standby.html -[wal-g]: export-and-import.md#database-only-backup-tools diff --git a/docs/production/export-and-import.md b/docs/production/export-and-import.md index c71445c5be..3424d8bdc0 100644 --- a/docs/production/export-and-import.md +++ b/docs/production/export-and-import.md @@ -63,7 +63,7 @@ service (or back): decommissioning a Zulip organization. - It's possible to set up [PostgreSQL streaming - replication](deployment.md#postgresql-warm-standby) + replication](postgresql.md#postgresql-warm-standby) and the [S3 file upload backend](upload-backends.md#s3-backend-configuration) as part of a high availability environment. @@ -526,7 +526,7 @@ it may be minutes before the backup is saved into S3 -- see [`archive_timeout`][archive-timeout] for how to set an upper bound on this. If you need always-current backup availability, Zulip also has -[built-in database replication support](deployment.md#postgresql-warm-standby). +[built-in database replication support](postgresql.md#postgresql-warm-standby). You can (and should) monitor that backups are running regularly via the Nagios plugin installed into diff --git a/docs/production/postgresql.md b/docs/production/postgresql.md index 87f0d8c1a6..b3ae52471a 100644 --- a/docs/production/postgresql.md +++ b/docs/production/postgresql.md @@ -168,6 +168,35 @@ su zulip -c '/home/zulip/deployments/current/scripts/setup/initialize-database' su zulip -c '/home/zulip/deployments/current/manage.py generate_realm_creation_link' ``` +## PostgreSQL warm standby + +Zulip's configuration allows for [warm standby database +replicas][warm-standby] as a disaster recovery solution; see the +linked PostgreSQL documentation for details on this type of +deployment. Zulip's configuration builds on top of `wal-g`, our +[streaming database backup solution][wal-g], and thus requires that it +be configured for the primary and all secondary warm standby replicas. + +In addition to having `wal-g` backups configured, warm standby +replicas should configure the hostname of their primary replica, and +username to use for replication, in `/etc/zulip/zulip.conf`: + +```ini +[postgresql] +replication_user = replicator +replication_primary = hostname-of-primary.example.com +``` + +The `postgres` user on the replica will need to be able to +authenticate as the `replication_user` user, which may require further +configuration of `pg_hba.conf` and client certificates on the replica. +If you are using password authentication, you can set a +`postgresql_replication_password` secret in +`/etc/zulip/zulip-secrets.conf`. + +[warm-standby]: https://www.postgresql.org/docs/current/warm-standby.html +[wal-g]: export-and-import.md#database-only-backup-tools + ## PostgreSQL vacuuming alerts The `autovac_freeze` PostgreSQL alert from `check_postgres` is particularly diff --git a/docs/production/requirements.md b/docs/production/requirements.md index 1a15d7af41..6e5c9818ee 100644 --- a/docs/production/requirements.md +++ b/docs/production/requirements.md @@ -248,5 +248,5 @@ impact Zulip's scalability, this [performance and scalability design document](../subsystems/performance.md) may also be of interest. [s3-uploads]: upload-backends.md#s3-backend-configuration -[streaming-replication]: deployment.md#postgresql-warm-standby +[streaming-replication]: postgresql.md#postgresql-warm-standby [contact-support]: https://zulip.com/help/contact-support diff --git a/docs/production/system-configuration.md b/docs/production/system-configuration.md index 62005ad743..7722f362b4 100644 --- a/docs/production/system-configuration.md +++ b/docs/production/system-configuration.md @@ -230,13 +230,13 @@ setting](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-R #### `replication_primary` -On the [warm standby replicas](deployment.md#postgresql-warm-standby), set to the +On the [warm standby replicas](postgresql.md#postgresql-warm-standby), set to the hostname of the primary PostgreSQL server that streaming replication should be done from. #### `replication_user` -On the [warm standby replicas](deployment.md#postgresql-warm-standby), set to the +On the [warm standby replicas](postgresql.md#postgresql-warm-standby), set to the username that the host should authenticate to the primary PostgreSQL server as, for streaming replication. Authentication will be done based on the `pg_hba.conf` file; if you are using password @@ -247,7 +247,7 @@ for authentication. If set to as true value, inhibits the nightly [`wal-g` backups][wal-g] which would be taken on all non-replicated hosts and [all warm standby -replicas](deployment.md#postgresql-warm-standby). This is generally only set if you have +replicas](postgresql.md#postgresql-warm-standby). This is generally only set if you have multiple warm standby replicas, in order to avoid taking multiple backups, one per replica.