AHMED ZBYR

AHMED ZBYR

Biker, EV Enthusiast

Apache CouchDB is an open-source, document-oriented NoSQL database that stores JSON documents, exposes a native HTTP/RESTful API (on TCP port 5984 by default), indexes data using JavaScript MapReduce views, and supports multi-master incremental replication with automatic conflict detection.

This guide walks through installing CouchDB on Ubuntu 14.04 LTS, configuring its network bind address in /etc/couchdb/local.ini, creating an administrator account (to exit CouchDB’s insecure “Admin Party” mode), and verifying the HTTP API and Futon/Fauxton web interface.

Support Warning: Ubuntu 14.04 LTS and CouchDB 1.x have reached End of Life. Modern CouchDB 3.x installations require creating an admin user at setup time and use the Fauxton web UI (/_utils).

Step 1: Add the Official CouchDB PPA and Install CouchDB

Install software-properties-common so add-apt-repository is available, add the CouchDB stable repository, and update APT package metadata:

sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:couchdb/stable
sudo apt-get update -y

If an older distro-packaged version of CouchDB is already present, remove it first:

sudo apt-get remove -y couchdb couchdb-bin couchdb-common

Install CouchDB:

sudo apt-get install -V -y couchdb

Step 2: Configure Network Binding and Admin Credentials (/etc/couchdb/local.ini)

By default, CouchDB listens only on 127.0.0.1:5984. If remote application servers, replication peers, or a Nagios monitoring server need to reach CouchDB over the network, update /etc/couchdb/local.ini (changes in local.ini override default.ini and are preserved across package upgrades).

1. Stop the CouchDB Service

sudo stop couchdb
# Or: sudo service couchdb stop

2. Edit /etc/couchdb/local.ini

Update bind_address under [httpd] and define an administrator username and password under [admins] (CouchDB automatically hashes the plain-text password in local.ini the next time it starts):

[httpd]
port = 5984
bind_address = 0.0.0.0

[admins]
admin = REPLACE_WITH_STRONG_PASSWORD

Security Note: Never set bind_address = 0.0.0.0 without configuring an account under [admins] and restricting port 5984 via your firewall (ufw or iptables). In CouchDB 1.x/2.x, an instance with no entries under [admins] runs in “Admin Party” mode, granting every anonymous HTTP client full administrative privileges.

3. Start CouchDB

sudo start couchdb
# Or: sudo service couchdb start

Step 3: Verify the CouchDB HTTP Endpoint and Web UI

Test the HTTP REST endpoint using curl:

curl http://127.0.0.1:5984/

Expected JSON response:

{
  "couchdb": "Welcome",
  "uuid": "85fb71bf700c17267fef77535820e371",
  "version": "1.6.1",
  "vendor": {
    "name": "Ubuntu",
    "version": "14.04"
  }
}

You can also open the web administration interface in your browser at:

http://couchdb-server:5984/_utils/

Basic curl Database Operations

# List all databases
curl http://127.0.0.1:5984/_all_dbs

# Create a new database named 'mydb' (authenticated as admin)
curl -X PUT http://admin:REPLACE_WITH_STRONG_PASSWORD@127.0.0.1:5984/mydb

References

You May Also Enjoy