Intro

This documentation is meant to be a general guideline, unfortunately we can not write documentation to cover all combination of operating system (Debian/Ubuntu/Alpine/FreeBSD/NetBSD/OpenBSD, etc), virtualization (no virtualization, Docker, Portainer, Proxmox, Kubernetes, Bhyve, Jails, etc), and firewall (ufw, firewalld, PF, etc).

We are happy to add notes to a particular system setup, if you would like to contribute, please contact us at [email protected].

Software Requirements

  • CouchDB
  • NGINX or HAProxy

CouchDB

When using CouchDB, make sure it has an admin account. This account is used to create the groups you need.

Important: use the admin account only to create groups. For day-to-day operations use a regular account. Consider an admin account in CouchDB as a root accound in Linux and BSD servers.

NGINX

Point all requests starting with /_dashboard to the HTML file you receive.

upstream couchdbbackend {
  server 127.0.0.1:5984;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;

  location ^~ /_dashboard {
    root /var/www;
    try_files /_dashboard.html =404;
  }

  location / {
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://couchdbbackend;
  }
}

Example deployment: NGINX in the host, CouchDB with docker-compose

For this example deployment we will assume you already get your TLS certificate with Let’s Encrypt.

CouchDB with docker-compose

Create a directory for the the initial files, for this example we will create /couchdb/:

mkdir /couchdb

Create a file called docker-compose.yml in the directory you just created with this content:

services:
  database:
    image: couchdb:3.4.3
    environment:
      - COUCHDB_USER=superadmin
      - COUCHDB_PASSWORD=changethisplease
      - NODE_NAME=couchdb01
    ports:
      - 5984:5984
    volumes:
      - database:/opt/couchdb/data
    configs:
      - source: nouveau.ini
        target: /opt/couchdb/etc/local.d/nouveau.ini

  nouveau:
    image: couchdb:3.4.3-nouveau
    volumes:
      - index:/opt/nouveau/data

volumes:
  database:
  index:

configs:
  nouveau.ini:
    content: |
      [couchdb]
      single_node=true
      [nouveau]
      enable = true
      url = http://nouveau:5987

Start CouchDB with docker compose up or docker compose up -d. Go to http://localhost:5984 to make sure everything is working, aditionally you can test with curl:

curl http://localhost:5984/_up
{"status":"ok","seeds":{}}

An output similar to this means your server is working:

{"status":"ok","seeds":{}}

Note:

You may need to enable CORS after setting up your CouchDB server, for that go to Configuration -> CORS and configure according to your setup.

NGINX

Configure your NGINX with this config file below, remove the certificate entry if you don’t need it:

upstream couchdbbackend {
  server 127.0.0.1:5984;
}

server {
  listen 80;
  server_name app.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;

  location ^~ /_dashboard {
    root /var/www;
    try_files /_dashboard.html =404;
  }

  location / {
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://couchdbbackend;
  }
}

Go to your host or ip address.

Notes:

  • On FreeBSD usually your NGINX configuration is in /usr/local/etc/nginx/http.d/ and certificate is in /usr/local/etc/letsencrypt/
  • On Alpine Linux configuration for NGINX is in /etc/nginx/http.d/