CouchDB replication fails when running in a Docker container

Almost all of my CouchDB instances lately have been run inside of Docker containers. As a Windows user, installing and using CouchDB through Docker has been such a massive improvement over the janky "old" way that I cringe just thinking about installing a permanent, non-containerized instance on my machines or servers.

Typically my dev setup for any project over the past year or so has been to set up a Docker compose file that starts both the developed app in one container, and a database in another container, and then networks them together. Sometimes its a SQL database, sometimes it's PostgreSQL, and sometimes it's CouchDB.

Anybody that's familiar with Docker compose and Docker development in general knows that sometimes the data will be cleared and your database will reset back to an empty state. Hopefully that's only going to happen when you want to reset your app's data back to "scratch", but sometimes (if you're clumsy like me) you might do a simple docker system prune on your dev machine and woops there goes the data! Good thing it's not production. 😅

Whatever the reason for your sudden absence of data, you might need to reseed your database with data that you know is valid. CouchDB's replication system is perfect for this -- just log in to the built-in Futon management database (at localhost:5984 by default) and start a new replication job from an existing remote database to your local database.

Starting a CouchDB replication job

After starting a replication job you'd usually be good to go with a freshly seeded database, but after I started containerizing my CouchDB my replications suddenly started failing. They'd immediatley error out and start retrying, with no obvious error message until the replication job eventually failed completely.

It turns out that, for some reason I haven't been able to figure out, the containerized CouchDB instance thinks its own address is http://any:5984. When you try to or from the containerized CouchDB instance, Futon will think the local instance's address is http://any:5984/database_name -- an obviously bizarre and invalid address that the container will subsequently fail to connect to.

Maybe I missed a configuration step somewhere, I'm honestly not sure, but thankfully this is really easy to fix. All you need to do is change the local target to a remote target, but use http://localhost:5984/database_name as the address.

Use a remote database as the target with localhost:5984

Voila, replication works once again!

Learn how to build rock solid Shopify apps with C# and ASP.NET!

Did you enjoy this article? I wrote a premium course for C# and ASP.NET developers, and it's all about building rock-solid Shopify apps from day one.

Enter your email here and I'll send you a free sample from The Shopify Development Handbook. It'll help you get started with integrating your users' Shopify stores and charging them with the Shopify billing API.

We won't send you spam. Unsubscribe at any time.