chore(#2081): add page about couchdb config #2109
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mrjones-plip
requested changes
Jan 13, 2026
Contributor
mrjones-plip
left a comment
mrjones-plip
left a comment
There was a problem hiding this comment.
This is really helpful! I know we've seen some deployments try and run vanilla CouchDB and having this document will really reinforce the importance of running the CHT version.
I made some minor wording changes to tighten things up. Also, they're officially CouchDB not CouchDb ; )
Another semi-related change would be to reduce duplication of "database" in the left hand nav. It's currently:
Database
Configuration
Database Schema
Document hydration
Document auditing
Database Conflicts
CouchDB Authentication
PostgreSQL Analytics
And I think this is easier to parse. I removed all "CouchDB" , "Database" and "Documents" , "Authentication" gets renamed to "Invalidating Sessions" and then sort all these at the top. PostgreSQL link goes at the bottom. Am totally open about this though! (nix it all together, add back in "Document" for hydr. and Conflic., what ever!).
However, when I re-read the new nav, I feel link this easily enough all falls under "Database" :
Database
Auditing
Configuration
Conflicts
Hydration
Invalidating Sessions
Schema
PostgreSQL Analytics
Comment on lines
+14
to
+17
| CouchDb is free and open source NoSQL database used as the primary store for all app data and configuration. CouchDB is offers out-of-the-box replication, which is the process of sending the data to another database and back again, which makes it ideal for replicating data to the phone for offline access. See more at the [CouchDB](https://couchdb.apache.org) site. | ||
| The CHT bundles a version of CouchDB with specific [configuration](/technical-overview/data/config) changes to improve performance, reliability, and is tailored for use with the CHT workflows. | ||
|
|
||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| CouchDb is free and open source NoSQL database used as the primary store for all app data and configuration. CouchDB is offers out-of-the-box replication, which is the process of sending the data to another database and back again, which makes it ideal for replicating data to the phone for offline access. See more at the [CouchDB](https://couchdb.apache.org) site. | |
| The CHT bundles a version of CouchDB with specific [configuration](/technical-overview/data/config) changes to improve performance, reliability, and is tailored for use with the CHT workflows. | |
| [CouchDB](https://couchdb.apache.org) is free and open source [NoSQL](https://en.wikipedia.org/wiki/NoSQL) database used as the primary store for all CHT data and configuration. With out-of-the-box replication, CouchDB is ideal for for offline access. This allows mobile handsets to work offline and trivially replicate data when back online. The CHT bundled CouchDB has specific [configuration changes](/technical-overview/data/config) for performance and reliability which are tailored for CHT workflows. |
| The CHT bundles a version of CouchDB with specific [configuration](/technical-overview/data/config) changes to improve performance, reliability, and is tailored for use with the CHT workflows. | ||
|
|
||
|
|
||
| The CHT has a range of CouchDB databases for storing different types of data. By default, databases all start with the prefix "medic". |
Contributor
There was a problem hiding this comment.
Suggested change
| The CHT has a range of CouchDB databases for storing different types of data. By default, databases all start with the prefix "medic". | |
| Note that all 7 CHT databases in CouchDB start with the prefix `medic` as shown below. Database that start with `_`, like `_users` are native CouchDB databases. |
| keywords: config, configuration | ||
| --- | ||
|
|
||
| Due to CHT particularities, several changes have been made to CouchDb configuration. These changes are designed to improve performance, reliability, and to better support the CHT workflows. The configuration is bundled with the CouchDb docker image and can be found in the [CHT repository](https://github.com/medic/cht-core/blob/master/couchdb/10-docker-default.ini). |
Contributor
There was a problem hiding this comment.
Suggested change
| Due to CHT particularities, several changes have been made to CouchDb configuration. These changes are designed to improve performance, reliability, and to better support the CHT workflows. The configuration is bundled with the CouchDb docker image and can be found in the [CHT repository](https://github.com/medic/cht-core/blob/master/couchdb/10-docker-default.ini). | |
| Due to CHT particularities, several changes have been made to default CouchDB configuration. These changes are designed to improve performance, reliability, and to better support the CHT workflows. The configuration is bundled with the CouchDB Docker image and can be found in the [CHT repository](https://github.com/medic/cht-core/blob/master/couchdb/10-docker-default.ini). |
| @@ -0,0 +1,46 @@ | |||
| --- | |||
| title: "CHT CouchDb configuration" | |||
Contributor
There was a problem hiding this comment.
Suggested change
| title: "CHT CouchDb configuration" | |
| title: "CHT CouchDB configuration" |
| linkTitle: "Configuration" | ||
| weight: 1 | ||
| description: > | ||
| Overview of CouchDb configuration used by default by CHT-CouchDB |
Contributor
There was a problem hiding this comment.
Suggested change
| Overview of CouchDb configuration used by default by CHT-CouchDB | |
| CHT specific changes to default CouchDB configurations |
|
|
||
| Due to CHT particularities, several changes have been made to CouchDb configuration. These changes are designed to improve performance, reliability, and to better support the CHT workflows. The configuration is bundled with the CouchDb docker image and can be found in the [CHT repository](https://github.com/medic/cht-core/blob/master/couchdb/10-docker-default.ini). | ||
|
|
||
| For more information about CouchDb configuration options, see the [CouchDb documentation](https://docs.couchdb.org/en/stable/config/index.html). |
Contributor
There was a problem hiding this comment.
Suggested change
| For more information about CouchDb configuration options, see the [CouchDb documentation](https://docs.couchdb.org/en/stable/config/index.html). | |
| For more information about CouchDB configuration options, see the [CouchDB documentation](https://docs.couchdb.org/en/stable/config/index.html). |
|
|
||
| {{< callout >}} | ||
| **Note:** | ||
| Some CHT configuration values are the same as the default CouchDb values. This is due to changes that can occur depending on the CouchDb version, while the CHT needs the configuration value fixed. |
Contributor
There was a problem hiding this comment.
Suggested change
| Some CHT configuration values are the same as the default CouchDb values. This is due to changes that can occur depending on the CouchDb version, while the CHT needs the configuration value fixed. | |
| Some CHT configuration values are the same as the default CouchDB values. This is intention and ensures when changes occur in CouchDB version over time, the CHT still has the value it needs. |
| #### Configuration Field Explanations | ||
| | [Section] Field = value | Description | Default value | | ||
| |----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `[fabric]`<br>`request_timeout = 31536000` | Sets internal Cluster CouchDb request timeout in seconds. | 60000. Not documented. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `[fabric]`<br>`request_timeout = 31536000` | Sets internal Cluster CouchDb request timeout in seconds. | 60000. Not documented. | | |
| | `[fabric]`<br>`request_timeout = 31536000` | Sets internal Cluster CouchDB request timeout in seconds. | 60000. Not documented. | |
| | [Section] Field = value | Description | Default value | | ||
| |----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `[fabric]`<br>`request_timeout = 31536000` | Sets internal Cluster CouchDb request timeout in seconds. | 60000. Not documented. | | ||
| | `[query_server_config]`<br>`os_process_limit = 1000` | Sets the maximum number of OS processes that can be spawned by CouchDb. | [100](https://docs.couchdb.org/en/stable/config/query-servers.html#query_server_config/os_process_limit) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `[query_server_config]`<br>`os_process_limit = 1000` | Sets the maximum number of OS processes that can be spawned by CouchDb. | [100](https://docs.couchdb.org/en/stable/config/query-servers.html#query_server_config/os_process_limit) | | |
| | `[query_server_config]`<br>`os_process_limit = 1000` | Sets the maximum number of OS processes that can be spawned by CouchDB. | [100](https://docs.couchdb.org/en/stable/config/query-servers.html#query_server_config/os_process_limit) | |
| | `[couchdb]`<br>`attachment_stream_buffer_size = 16384` | Sets the size of the buffer used to stream attachments. | [4096](https://docs.couchdb.org/en/stable/config/couchdb.html#couchdb/attachment_stream_buffer_size) | | ||
| | `[couchdb]`<br>`max_document_size = 4294967296` | Limit maximum document body size. | [8000000](https://docs.couchdb.org/en/stable/config/couchdb.html#couchdb/max_document_size) | | ||
| | `[couchdb]`<br>`changes_doc_ids_optimization_threshold = 40000` | Change requests with docs ids optimization treshold | 100. Not documented. | | ||
| | `[chttpd]`<br>`port = 5984` | Sets the port on which CouchDb listens for HTTP requests. | [5984](https://docs.couchdb.org/en/stable/config/http.html#chttpd/port) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `[chttpd]`<br>`port = 5984` | Sets the port on which CouchDb listens for HTTP requests. | [5984](https://docs.couchdb.org/en/stable/config/http.html#chttpd/port) | | |
| | `[chttpd]`<br>`port = 5984` | Sets the port on which CouchDB listens for HTTP requests. | [5984](https://docs.couchdb.org/en/stable/config/http.html#chttpd/port) | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
#2081
License
The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.