Introducing: How to Host Your Own CouchDB with CouchDB Minihosting posted Wednesday, March 5, 2025 by The Neighbourhoodie Team
CouchDB is a great database, but there’s a slight lack of easy-to-use, affordable CouchDB hosters, or hosting services that offer CouchDB as an add-on. So we decided to make rolling your own hosted CouchDB as simple and quick as we could: with our Open Source CouchDB Minihosting. Let’s have a look!
What is CouchDB Minihosting?
It’s a set of scripts that make it really simple to set up a CouchDB instance on any Linux hosting service in a matter of minutes.
CouchDB Minihosting gives you:
- A CouchDB instance.
- HTTPS certificates with autorenewal via letsencrypt.
- haproxy and nginx for routing, exposing the CouchDB API at
/_api. - Scripts for deploying and rolling back a webapp that lives alongside CouchDB on the same server. This is a basic approach that allows deploying directly from a dev machine.
CouchDB and the services all run inside Docker, and the whole thing can be set up quickly and with very little hassle. All you need to bring is a Linux VM with a domain pointing to it, an ssh key pair, and some basic terminal knowledge. We like using the smallest DigitalOcean Droplet (the 4 USD one) with Ubuntu 24.10x64 to get started.
CouchDB Minihosting is the perfect first step if you want to host your own CouchDB quickly, cheaply and on your own terms!
We’ll walk through the installation process later in this post, but if you’re rearing to get started, the CouchDB Minihosting repo has all the documentation you’ll need.
Who is CouchDB Minihosting for?
Basically, anyone who wants to run a remote CouchDB that isn‘t running a large, hight-traffic, or high-availability production app. Proofs-of-concept, demos, tools for yourself or your team (Obsidian LiveSync comes to mind), even smaller or early-stage production apps up to a couple of thousand users should be totally fine, depending on your exact use case and how beefy a VM you’re willing to pay for.
CouchDB Minihosting Walkthrough
So, how does it all work?
Assuming that you have a Linux VM you’ve already sshd into:
- Clone the CouchDB Minihosting repo:
git clone https://github.com/neighbourhoodie/couchdb-minihosting.git - Hop into that folder and adapt the
.envfile to your needs - Run the install script with
./install.sh
And that’s it. You’ll end up with a running CouchDB instance, with an admin user and a Fauxton admin panel you can log in to. Boom.
Using the Deploy Script
The ./install.sh script also sets up a deploy user which the deploy and rollback scripts will use. The deploy user needs to be authorised to ssh into the host server, so you’ll need to add the correct public key to the server. The /deployment/README.md will guide you through this. Beyond that, all you need to do is:
- Copy the deploy scripts to your web app repo and give them execution permissions
- Adapt the
deploy.envfile to your needs - Build your app and run
./deploy.sh
Deployed a broken build? ./rollback.sh will roll back to the previous deployment in seconds. Phew.
What if CouchDB Minihosting Isn’t Enough For You?
CouchDB Minihosting is intended as a convenient starting point for your CouchDB adventures and to provide a service akin to the “one-click-install” MySQL databases offered by many webhosters. You can do a lot with those, but like CouchDB Minihosting, they won’t scale particularly far. At some point, you may run into limits: requests per second, execution speed, connection limits, availability etc., and that’s fine. This isn’t the one-size-fits-all solution that scales infinitely and has magical performance, it’s like your first bike: It won’t get you up Mont Ventoux, but it will get you into cycling.
If you’ve built something successful on CouchDB Minihosting and need to scale up: we’re here for you! We offer a wide range of commercial services around CouchDB, and designing and implementing scalable setups is one of them. Already scaled up on your own? We offer an Architecture Review where we check your setup and prepare a report with actionable improvement suggestions.
In any case, if you need any kind of commercial support for CouchDB, we can provide it. Get in touch and we’ll figure something out!
« Back to the blog post overview