Setting Up Apache CouchDB for Development: One Click or a Couple of Commands

Getting a database project running locally can feel like a scavenger hunt. You install dependencies, chase down version mismatches, and then realize the build process expects something you don't have. Apache CouchDB has clearly thought about this problem, because the README offers two paths into a working development environment: a single click in VS Code, or a manual setup that's refreshingly short.

What It Does

Apache CouchDB is an open-source document-oriented database. The repository you're looking at is the database itself—the source code for the whole thing. If you want to contribute, fix a bug, or just poke around inside a database engine, this is where you'd start.

The README spends most of its time on one thing: getting you from a fresh clone to a running cluster. And it does that with two options. The first is a devcontainer that spins up everything for you. The second is the more traditional route—install the dependencies, run ./configure && make, and you're off. Both paths lead to the same place: a local three-node cluster listening on port 5984.

Why It's Cool

The one-click devcontainer is a genuinely nice touch. If you've got VS Code and Docker installed, you click a badge in the README and VS Code handles the rest: it installs the Remote - Containers extension if you don't have it, clones the source into a container volume, and boots a dev environment. The container even runs ./configure && make automatically the first time it's created. That's a slow first startup, but the tradeoff is that once it's done, everything works. You can run ./dev/run, ./dev/run --admin=admin:admin, or make check immediately. Subsequent startups are fast because the build is already done.

The manual path is short, too. If containers aren't your thing, the README doesn't leave you stranded. Install the dependencies documented in the install docs, run ./configure && make, and then—this is the part I like—you don't need make install. Just run ./dev/run to spin up three nodes. No system-wide installation, no messing with your machine's package manager. Everything stays local to the repo.

There's a haproxy option for realistic testing. Run ./dev/run --with-haproxy --haproxy=/path/to/haproxy and you get a caching layer sitting in front of your local cluster. That's the kind of setup you'd normally have to build by hand if you wanted to test how CouchDB behaves behind a proxy.

The Fauxton admin-party gotcha is documented. This is a small thing, but it tells you the README was written by people who actually use the thing. If you're working on Fauxton (CouchDB's web interface) and you try to fix the admin party via the button, it won't work. You have to run ./dev/run --admin=username:password from the command line. If you want to keep the admin party, just omit the flag. That's the kind of detail that saves you twenty minutes of confusion.

How to Try It

There are two ways to get started. Pick whichever fits your workflow.

Option 1: The VS Code devcontainer

If you already have VS Code and Docker installed, click the badge in the README or follow the link to the redirect URL. VS Code will install the Remote - Containers extension if needed, clone the repo into a container volume, and spin up the dev environment. It'll run ./configure && make automatically the first time, so give it a few minutes. After that, you're ready to go.

Option 2: Manual setup

1. Install the dependencies listed in the install docs (the README points you to INSTALL.Unix for Mac and Ubuntu, or INSTALL.Windows for Windows).
2. Clone the repo and run:

./configure && make

1. Start a three-node cluster:

./dev/run

If you want an admin user, use:

./dev/run --admin=username:password

If you want haproxy in front of the cluster:

./dev/run --with-haproxy --haproxy=/path/to/haproxy

Once it's running, you'll have a local cluster on port 5984. You can verify your installation by browsing to http://127.0.0.1:5984/_utils/#verifyinstall.

You can find the repository at https://github.com/apache/couchdb. The README also links to README-DEV.rst for more detail, and the contributing guide is at https://github.com/apache/couchdb/blob/main/CONTRIBUTING.md.

Final Thoughts

This README is short, but it's honest about what you need and what you'll get. The devcontainer is the easiest path if you're already in VS Code, and the manual setup is straightforward enough that you won't feel punished for choosing it. If you've been curious about CouchDB's internals or you want to contribute to a mature Apache project, this is a low-friction way to get a working environment without fighting your system's package manager. The three-node cluster running locally with no make install is a small but meaningful quality-of-life detail that more projects could learn from.

Follow @githubprojects for more developer tools and open source projects.