CouchDB in WSL: Single-Node Setup, Revisions, and Local Replication

Apache CouchDB is convenient for local application work that uses JSON documents, HTTP APIs, revision histories, and replication. A single CouchDB process inside WSL is a useful development node, but it is not a cluster and does not provide a second failure domain. The WSL distribution may stop or be removed, so keep local document data disposable unless there is an explicit backup and restore process.

CouchDB’s single-node setup is also more than simply starting the service. The administrator account, single-node configuration, and system databases affect whether setup is complete. Use the current CouchDB 3.5 documentation for its package behavior and avoid mixing old 2.x or 3.x snippets without checking their version notes.

Install and complete the single-node setup

Follow the official Unix installation guide for the WSL distro’s supported package. Start the package-owned service and inspect its journal:

systemctl status couchdb --no-pager
sudo systemctl start couchdb
systemctl is-active couchdb
sudo journalctl --unit couchdb -n 100 --no-pager

Service unit naming can vary by package. Use the installed unit and config path rather than launching an extra foreground server against the same data directory.

Complete setup with the CouchDB setup wizard in Fauxton or follow the documented single-node configuration procedure. The setup must create the _users and _replicator system databases. _global_changes is needed only when the server-wide database changes feed is required; CouchDB’s version history notes that the setup wizard stopped creating it automatically in 3.0, while the current single-node page still describes it among the wizard-created databases. Verify the actual system database list for the installed release instead of assuming this optional database exists. An alternative is configuring the single-node option and restarting; if using a manual configuration path, verify that the required system databases exist. A process listening on port 5984 is not enough to prove setup is complete.

The root endpoint reports server metadata, while the documented readiness endpoint is intended to confirm that the server is up and ready to respond. Test the local service:

curl --fail --silent --show-error http://127.0.0.1:5984/_up
curl --fail --silent --show-error http://127.0.0.1:5984/

The /_up endpoint is designed to report readiness without requiring authentication in standard CouchDB configurations; other API routes, including root metadata depending on server policy, can still return an authorization error while the process is running. Separate HTTP authorization failures from transport and readiness failures. Use the documented local admin flow for protected operations; do not disable authentication just to make a health check appear green.

Treat document revisions as concurrency control

CouchDB assigns revisions to documents. An update normally includes the current revision identifier, and a stale revision is rejected as a conflict instead of silently overwriting a concurrent update. The application should handle this conflict deliberately: fetch the current document, merge or resolve the competing change, and retry only when its business rules allow it.

Use an isolated database and deterministic document IDs for test fixtures. A minimal API exercise creates a local database and inserts a document:

curl --fail --silent --show-error --user "$COUCHDB_USER" \
  -X PUT http://127.0.0.1:5984/wsl_lab

curl --fail --silent --show-error --user "$COUCHDB_USER" \
  -X PUT http://127.0.0.1:5984/wsl_lab/events-1 \
  -H 'Content-Type: application/json' \
  --data '{"kind":"test","value":1}'

Set the username variable locally; curl prompts for the password when only a username is supplied. Do not put a real password in the command text, source control, or shell history. The first request can report that the database already exists; treat that as an explicit fixture-state decision rather than ignoring all errors.

The response to a document write includes a revision. Preserve it when updating that document. A second write that uses an old revision can return HTTP 409, which is a concurrency signal, not necessarily a server fault. Tests should exercise one normal update and one deliberately stale update so the client has a defined conflict behavior.

Use document IDs that are deterministic for the domain when the application needs idempotent create behavior, or let CouchDB assign an ID when uniqueness is not part of the requirement. Do not assume that a deterministic ID makes concurrent writes merge automatically. The winning revision and conflict handling remain part of the application’s data model. If replication can produce conflicting revisions, test how the application resolves them instead of silently discarding a branch.

Use changes feeds and replication for the right problem

CouchDB’s changes feed exposes changes to documents and can be consumed by applications or replication jobs. It is not equivalent to a broker queue with arbitrary delivery and retention policies. A client that needs durable application processing should checkpoint its own progress and define how it handles replays, deleted documents, filtered feeds, and reconnects.

CouchDB replication synchronizes document revisions between databases, but local replication tests do not establish cluster high availability. A single WSL node replicating to another local database or remote endpoint is testing replication protocol and conflict behavior, not service failover. Distinguish a database cluster’s shard placement from database replication jobs; they solve different operational requirements.

For a reproducible test, record source and target URLs, database names, filter behavior, and whether replication is one-shot or continuous. Run a one-shot sync on a disposable pair, inspect the replication result, and then introduce a controlled competing edit to see how revisions and conflicts are represented. Do not delete the source until the target’s content and expected revision state have been verified.

Inspect databases, indexes, and background work

Use the HTTP API and Fauxton to inspect the database list, document count, indexes, and active tasks. An administrator-only endpoint may require authenticated access. Keep the account role explicit and use the smallest local permissions required by the application test. Do not put production-like personal data into a workstation database unless there is an approved handling process.

A useful acceptance test should verify the document by ID, read back the fields the application depends on, test an update with its current revision, and confirm a stale update conflicts. For a changes-feed consumer, write two known documents, resume from the expected sequence, and verify the consumer neither skips nor repeatedly applies records. Record the server response and request parameters with the test.

When validating a local integration, distinguish server-level acceptance from API behavior. The root endpoint can report version and feature metadata; the readiness endpoint reports whether CouchDB can respond. Neither proves a database exists, that a document write is authorized, or that a view is current. Build a small checklist that checks transport, authentication, database presence, one create/read/update cycle, and any index or feed behavior required by the application.

When a query or view is slow, inspect whether the relevant index exists and is current before increasing resource limits. Building indexes consumes CPU and disk and may run in the background. Startup readiness can occur before all application-specific views are warm. For workloads that rely on a design document or index, include index readiness in the application acceptance check.

Keep the database path and WSL lifetime explicit

Keep CouchDB’s package-managed data directory on the Linux filesystem owned by the distro. Do not copy its live database files while writes continue and treat them as a consistent backup. Use a documented backup or replication method, and restore into a separate test instance before declaring the backup usable.

An enabled systemd unit can start CouchDB when the distribution is running; it cannot prevent WSL from shutting down. Windows sleep, restart, servicing, and an explicit distro shutdown interrupt the endpoint. A persistent file under the VHDX is still one local copy. If local test data matters across machine loss, store a verified backup outside the distribution disk.

If Windows-native software connects to the service, test from that Windows process and validate the WSL listener, route, and authentication independently. Do not change the listen address to every interface as a shortcut. Linux-to-Linux loopback success does not prove that the Windows client uses the expected hostname, port, database, or credentials.

Acceptance criteria for a WSL CouchDB lab

Accept the setup when a clean distribution installs one package-owned server, the single-node wizard or configuration procedure completes, the readiness endpoint responds, a user database can be created, document revisions behave as expected, and a controlled restart preserves only the state that the local policy promises.

Document the CouchDB version, distro release, unit, data path, administrator setup, system database state, and whether local records are disposable. A single-node instance is suitable for application development and replication experiments. It does not prove clustered shard availability, production recovery, or continuous service uptime; validate those requirements in their target environment.

Related:

Sources: