Skip to content

Instantly share code, notes, and snippets.

Last active April 19, 2024 15:03
Show Gist options
  • Save Ravenstine/fb350f5af391aee641d024a74a087b8e to your computer and use it in GitHub Desktop.
Save Ravenstine/fb350f5af391aee641d024a74a087b8e to your computer and use it in GitHub Desktop.
Fast CouchDB setup in AWS

Fast CouchDB setup in AWS

CouchDB is a NoSQL database for storing JSON documents. It comes with a REST API out of the box so your client applications can persist data while requiring you to write little or no server-side code. CouchDB's killer feature is its ability to easily replicate, which allows for horizontal scaling, easy backup, and for client adapters to synchronize documents. This is perfect if you want to write an application that is offline-first. It's become my go-to database when creating new projects, along with PouchDB as the client adapter.

This is my recipe for quickly spinning up a CouchDB instance in AWS. The end result will support HTTPS/TLS so that your application will be secure and not face a mixed content warning if it's hosted on an HTTPS-only web server, preventing it from connecting to CouchDB.

I am writing this for those with an understanding of AWS concepts and who can find their way around the AWS console.

Install CouchDB in an EC2/ECS instance

The easiest way to get CouchDB running right out of the box is to use the official Docker image.

Elastic Container Service(or ECS) can spin up clusters of EC2 instances with Docker preinstalled and with whatever images you specify.

Follow these rough steps:

  1. Create a new ECS cluster with a single instance.
  2. Make a new ECS task that has klaemo/couchdb as the image and with port 5984 mapped to 5984.
  3. Run the task on your ECS instance.

If you navigate to your instance in the EC2 panel, you can find the IP address of your container. Go to http://<your instance ip>:5984/_utils and CouchDB's Fauxton interface should come up. This indicates that you have installed CouchDB successfully.

Alternatively, you can spin up an EC2 instance from scratch and install/manage Docker yourself. I recommend ECS because it's just faster and having a cluster may be useful later on.

Set up an Elastic Load Balancer

It may seem unnecessary to create a load balancer for your database, but there are multiple reasons why this is a good idea:

  • An load balancer is assigned a subdomain you can use for your CouchDB instance instead of an IP address.
  • Load balancers allow you to swap EC2 instances without having to change your application configuration.
  • If you decide to horizontally scale your CouchdB(multiple instances replicating off each other), a load balancer will distribute connections to them.
  • ELB makes it easy to support HTTPS without having to do server configuration(no installing NginX or HAProxy).

The full guide to setting up a load balancer is here, but here are the rough steps:

  1. In the EC2 console panel, go to LOAD BALANCING > LOAD BALANCERS, and then click on Create Load Balancer.
  2. Choose Classic Load Balancer.
  3. For the option Create LB Inside, choose whichever option that has as the IP.
  4. Under Listener Configuration, change the Load Balancer Protocol to HTTPS, and change the Instance Port to 5984.
  5. Create a new security group – under Type, choose HTTPS.
  6. Under Configure Health Check, change the Ping Path to /. Leave all the other default settings alone.
  7. Add your EC2 instance in Add EC2 Instances.
  8. Skip adding tags.
  9. Create your load balancer.

Once you have a load balancer set up, it should have a DNS Name assigned to it under the domain. Copy this DNS name and navigate to it in your browser. If you get a JSON response that says "Welcome", your load balancer has been successfully configured.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment