# 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
[hello@standardn9.com](mailto:hello@standardn9.com).

# 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.
{: .alert .alert-info .text-secondary }

## 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/`