Apache CouchDB, like Redis, Cassandra, and MongoDB, is a NoSQL database. CouchDB stores data as JSON documents which are non-relational in nature. This allows users of CouchDB to store data in ways that look very similar to their real world counterparts.
You can manage CouchDB from the command line or from a web interface called Futon. Futon can be used to perform administrative tasks like creating and manipulating databases, documents, and users for CouchDB.
By the end of this article, you will:
Please complete the following prerequisites:
Note: While this tutorial assumes a non-root user, you can execute the steps below as the root
user as well, in case you don’t want to create a sudo user. Please note that if you do use a non-root user, you’ll be asked for your password the first time you execute a command with sudo
.
Before we can install CouchDB, we need to ensure that the server is set up for it.
Begin by updating the system:
- sudo apt-get update
Install the software that allows you to manage the source repositories:
- sudo apt-get install software-properties-common -y
Note: The -y
flag tells the apt-get
command to assume a Yes
response to all the prompts that might come up during the installation process. You can drop this flag if you prefer responding manually to the prompts.
Add the PPA that will help us fetch the latest CouchDB version from the appropriate repository:
- sudo add-apt-repository ppa:couchdb/stable -y
Warning: Great care should be taken while adding a new Personal Package Archive (PPA) to your server. Since anyone can create a PPA, there’s no guarantee that it can be trusted or that it is secure. In this case, the above PPA is an official one, maintained by the Apache CouchDB team.
Now that we have added a new PPA, let’s update the system so that it has the latest package information:
- sudo apt-get update
We are now ready to install CouchDB and Futon.
If you previously had CouchDB installed on this server, begin by removing the existing version:
- sudo apt-get remove couchdb couchdb-bin couchdb-common -yf
Note: If you have a fresh Droplet, you can ignore this step.
Now install CouchDB:
- sudo apt-get install couchdb -y
This will install CouchDB and Futon on your server.
By default, CouchDB runs on localhost and uses the port 5984. You can retrieve this basic information by running curl
from the command line:
- curl localhost:5984
Note: If you don’t have curl
installed, you can use the sudo apt-get install curl
command to install it.
You should get something similar to the following:
Output{"couchdb":"Welcome","uuid":"b9f278c743b5fc0b971c4e587d77582e","version":"1.6.1","vendor":{"name":"Ubuntu","version":"14.04"}}
You can now create a new database with the curl -X PUT
command:
- curl -X PUT localhost:5984/new_database
The results should look like this:
Output{"ok":true}
By default, some of the files and directories created when CouchDB is installed belong to the root user and group. While this is fine (albeit not advisable) during development, it could be a security risk in production.
When CouchDB is installed, it creates a user and a group named couchdb. In this section we will change the ownership and permission of the CouchDB files to the couchdb user and group.
Changing the ownership controls what the CouchDB process can access, and changing the permissions controls who can access the CouchDB files and directories.
Before changing the ownership and permissions, stop CouchDB:
- sudo stop couchdb
Change the ownership of the /usr/lib/couchdb
, /usr/share/couchdb
, and /etc/couchdb
directories, and the /usr/bin/couchdb
executable file, such that their owner is couchdb and they belong to the couchdb group.
- sudo chown -R couchdb:couchdb /usr/lib/couchdb /usr/share/couchdb /etc/couchdb /usr/bin/couchdb
Now, change the permissions of the /usr/lib/couchdb
, /usr/share/couchdb
, and /etc/couchdb
directories, and the /usr/bin/couchdb
executable file, such that the couchdb user and the couchdb group have complete access (to the CouchDB installation) while no other user has access to these files and directories.
- sudo chmod -R 0770 /usr/lib/couchdb /usr/share/couchdb /etc/couchdb /usr/bin/couchdb
All that’s left to do is restart CouchDB:
- sudo start couchdb
CouchDB should now be up and running without any of its files or directories belonging to either the root user or the root group.
CouchDB offers a convenient web-based control panel called Futon. We’re going to access it from your local workstation, tunneling the traffic through an SSH connection to your server. This means that only users with an SSH login to your server can access the Futon control panel.
To connect securely to CouchDB, without making it publicly available, you can create an SSH tunnel from your local port 5984 to the remote server’s port 5984.
You can use the following command, run from your local computer, to set up the tunnel:
- ssh -L5984:127.0.0.1:5984 sammy@your_server_ip
Note: Remember to replace sammy with your username and your_server_ip with the IP address of your Droplet.
While the connection is open, you can access Futon from your favorite web browser, using port 5984. Visit this URL to display the helpful Futon page:
http://localhost:5984/_utils
By default, all CouchDB users who access Futon do so with administrative rights. This is announced in the bottom right corner:
You can change this by clicking on the little Fix this link and creating new administrators.
Now that we have CouchDB up and running, let’s start using it.
Before an admin user is created, all users can access CouchDB with administrative privileges (although they require SSH access to the server first).
It’s a good practice to create an admin account for CouchDB, to prevent accidental or unauthorized data loss.
To do this, click the Fix this link that appears in the bottom right corner of Futon. This will bring up a screen that allows you to create a CouchDB admin user, as follows:
Enter the desired username and password:
After entering your new CouchDB username and a secure password, click the Create button. This will create the new admin user. The message in the bottom right corner of Futon will confirm this by showing a message similar to the following:
Note: The creation of an admin user prevents unauthorized users from deleting and modifying databases, design documents, and the CouchDB configuration. However, it doesn’t prevent them from creating or accessing documents.
Be careful about handing out SSH access to your server.
That’s it! Our CouchDB server is now fully configured.
To learn more about using the database, keep reading.
Futon has a very simple but useful user interface which allows you to perform basic CRUD operations (create, read, update, and delete).
In this section, we will create a new database named todos
, add a new document to it, and then retrieve, update, and delete this document.
Note: If you have created an admin user, you will have to be logged in as the administrator to create a new database.
Make sure you still have your SSH tunnel open. If not, open your connection to the server from your local computer with this command:
- ssh -L5984:127.0.0.1:5984 sammy@your_server_ip
Let’s begin by visiting the Futon page at http://localhost:5984/_utils/
.
Note: This section assumes that CouchDB is being accessed using an SSH tunnel that was set up as described in in the Accessing Futon section above. If your setup is different, make sure you access Futon at the correct URL.
To create a new database called todos
, click the Create Database link on the screen. This will bring up a dialog as follows:
Enter the name of the database and click the Create button.
This will create a new database named todos
and take you to a page where you can start creating and modifying documents in the newly created database.
Create Document
To create a new document, click the New Document link on the page.
This will open up a screen with a new document. This document will have just the _id
field. You can change the value of this field if you need to or you can leave it as is.
Click the Add Field link to add a new field to this document.
As can be seen above, we have added two fields named todo
and done
. By default, new fields have a null
value.
Double-click the value to change it.
In this example, we have double-clicked the value fields of todo
and done
and have entered the values Task 1
and false
respectively.
Once you have entered the values, either press the ENTER
key or click the little green check mark next the field to save its contents. (Failing to do this will leave the value of the field as null
.) This should look as follows:
To save the document, click the Save Document link. After the document is saved, you will see that a _rev
field has been added to it as follows:
Click on the todos
link (in the top bar next to the Overview
link) to view the newly-created document, as the only document in the todos
database.
Click on the key of the document (the ID) in the table to access the document details page.
On this page, you can edit and update the document fields as follows:
To edit a field value, double-click it and start editing.
You can delete any field (apart from the _id
and _rev
fields), add new fields, or change the values of existing fields. In this example, we have changed the value of the done
field from false
to true
as follows:
After you are satisfied with the changes, click the Save Document link to update the document. Once you do so, you’ll notice that the value of the _rev
field has been updated as well.
To delete a document, you can click the Delete Document link which will prompt you for confirmation:
Confirm by pressing the Delete button.
Futon will delete the document and take you to the todos
database page, which should now be empty, confirming that the document has indeed been deleted.
This section will illustrate how we can perform basic CRUD (create, read, update, and delete) operations on a CouchDB database from the command line using curl
.
Make sure you still have your SSH tunnel open. If not, open your connection to the server from your local computer with this command:
- ssh -L5984:127.0.0.1:5984 sammy@your_server_ip
Note: This section will use the database new_database
that was created in Step 2 (Installing CouchDB) above. This section will also assume that we are accessing CouchDB using an SSH tunnel as described in the Accessing Futon step above. If your setup is different, make sure you replace the URL, PORT, and the database names appropriately while executing the commands used below.
If you didn’t already create the database new_database
, please do so now. This command should be executed from your local workstation:
- curl -X PUT http://localhost:5984/new_database -u "admin:password"
- {"ok":true}
Since we added an admin user to CouchDB, we now have to send the admin username and password when creating a new database.
The results should look like this:
Output{"ok":true}
Let’s begin by creating a new document.
- curl -X POST -d '{"todo":"task 1", "done":false}' http://localhost:5984/new_database -H "Content-Type:application/json"
This command creates a new document in the new_database
database.
The -X
flag indicates that we are performing an HTTP POST operation. The -H
flag followed by the header sets the content type of this request as application/json
since we are POSTing a JSON document. Finally, the JSON document itself is included, along with the -d
flag.
The response of this operation is as follows:
Output{"ok":true,"id":"803da996e1524591ce773d24400004ff","rev":"1-2fc1d70532433c39c9f61480607e3681"}
The "ok":true
part of this response indicates that the operation was successful. The response includes the fields id
and rev
, which represent the document ID and the document revision respectively. Both these fields will be required in case this document needs to be modified or deleted.
In this example, the document ID was generated by CouchDB because we didn’t supply it with the command. If required, we can create a document with a unique ID that we have generated.
Create with Specified ID
Create a document with the ID random_task
:
- curl -X POST -d '{"_id":"random_task", "todo":"task 2", "done":false}' http://localhost:5984/new_database -H "Content-Type:application/json"
This command creates a new document with the ID set to random_task
. The response to this command is as follows:
Output{"ok":true,"id":"random_task","rev":"1-bceeae3c4a9154c87db1649473316e44"}
Create Multiple Documents
In addition to creating single documents, we can also create documents in bulk.
- curl -X POST -d '{"docs": [{"todo":"task 3", "done":false}, {"todo":"task 4", "done":false}]}' http://localhost:5984/new_database/_bulk_docs -H "Content-Type:application/json"
This command will create two documents as specified in the POST body. There are two slight differences, as compared to the single-document inserts:
docs
field. This field holds the array of documents that are to be inserted.http://localhost:5984/new_database
). The request for bulk inserts, however, POSTs to the http://localhost:5984/new_database/_bulk_docs
URL.The response of the bulk insert operation is as follows:
Output[{"ok":true,"id":"803da996e1524591ce773d24400007df","rev":"1-778fd61f8f460d0c1df1bb174279489d"},{"ok":true,"id":"803da996e1524591ce773d2440001723","rev":"1-dc9e84861bba58e5cfefeed8f5133636"}]
Retrieving a document from a CouchDB database is a simple matter of issuing an HTTP GET command. Let’s try to retrieve one of the documents we created above: the one called random_task
.
- curl -X GET http://localhost:5984/new_database/random_task
Note that the URL includes the ID (random_task
) of the document which is being retrieved. The response to this GET request, as shown below, contains the entire document along with the _id
and the _rev
fields, which can be used to update or delete this document.
Output{"_id":"random_task","_rev":"1-bceeae3c4a9154c87db1649473316e44","todo":"task 2","done":false}
While trying to update a document, it is important to include the _rev
field. CouchDB will reject any update request which doesn’t include a _rev
field. Since CouchDB updates the entire document, and not just parts of it, the entire document must be sent in the request body during an update operation.
To update the document that was created with the ID random_task
, we need to issue an HTTP PUT request as follows:
- curl -X PUT -d '{"_rev":"1-bceeae3c4a9154c87db1649473316e44", "todo":"task 2", "done":true}' http://localhost:5984/new_database/random_task
Be sure to replace the _rev
value with the string you received in the previous output.
This modifies the document and updates the done
field to true
. The response to this request is as follows:
Output{"ok":true,"id":"random_task","rev":"2-4cc3dfb6e76befd665faf124b36b7f1c"}
As can be seen in the response, the rev
field for this particular document changes after it has been updated. Any future request to update or delete this document will now have to use the newest rev
value.
Let’s use this new rev
value to delete this document using an HTTP DELETE request as follows:
- curl -X DELETE http://localhost:5984/new_database/random_task?rev=2-4cc3dfb6e76befd665faf124b36b7f1c
Just like the GET & PUT requests above, the DELETE request uses the URL that points to the document. However, it also includes an additional query parameter in the URL. This parameter, rev
, should have the latest _rev
value for the delete operation to be successful.
In this particular case, we use the value that was returned after the update operation in the previous step. The response to the above request is shown below.
Output{"ok":true,"id":"random_task","rev":"3-07d6cde68be2a559497ec263045edc9d"}
Starting, stopping and restarting the CouchDB service is quite straightforward. Complete these steps from the server.
To restart a running CouchDB instance, execute the following command:
- sudo restart couchdb
This command will restart a running CouchDB instance and display the process ID of the new instance. In case there is no instance of CouchDB running, executing this command will give a message like
Outputrestart: Unknown instance:
To stop a running CouchDB instance, execute the following command:
- sudo stop couchdb
Executing this command will stop any running CouchDB instance and provide a confirmation message like this:
Outputcouchdb stop/waiting
To start CouchDB, execute the following command:
- sudo start couchdb
If CouchDB wasn’t already running, executing this command will start CouchDB and provide a confirmation message like this:
Outputcouchdb start/running, process 12345
On the other hand, if there was a CouchDB instance already running then executing the above command will result in a message like this:
Outputstart: Job is already running: couchdb
In case you want to check the status of CouchDB, you can do so using the following command:
- sudo status couchdb
If CouchDB is running, this will give a message similar to the following:
Outputcouchdb start/running, process 12345
If CouchDB is not running, checking the status will result in something like:
Outputcouchdb stop/waiting
You now have a fully functional setup of CouchDB on your Droplet, which you can securely administer from your local machine using Futon or the command line.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
In “Step 3 — Securing the CouchDB Installation”
use: “sudo systemctl stop couchdb” if "“sudo stop couchdb” fails
I just set this up on a new Droplet with Ubuntu 16.04 LTS and CouchDB 1.6.1. Here are some steps I had to modify:
service couchdb start/stop
/var/lib/couchdb
instead of/usr/lib/couchdb
since the latter doesn’t exist.Nginx + SSL for secure access to Futon
In addition to this I installed
nginx
to proxy requests on port 443 (HTTPS) to Futon, setting up an SSL certificate in the process using https://letsencrypt.org/.I wrote up a blogpost on how to do this -> https://hiddentao.com/archives/2018/05/10/setup-couchdb-futon-secure-nginx-proxy/
If I installed CouchDB on a DO droplet, then I cannot acces Futon via browser on the
localhost:5984
adress. I also cannot acces it viamydropletip:5984
as it is unable to establish a connection.Can you please tell me where do I change this adress from?
Got this far…
sudo chown -R couchdb:couchdb /usr/lib/couchdb /usr/share/couchdb /etc/couchdb /usr/bin/couchdb
I get this error… chown: cannot access ‘/usr/lib/couchdb’: No such file or directory
The other locations appear to exist, but following the tutorial, this did not seem to be created. Help?
EDIT…
I found this location and changed the ownership here… would love a confirmation that this is correct…
/usr/lib/x86_64-linux-gnu/couchdb
If using Ubuntu 16.04 (and likely 15+), please stop and start couchdb with the following commands (to account for Systemd vs the older Upstart)
Here is a one click deployment solution for running Jenkins on Digital Ocean. I would love to hear any feed back. https://digitaldock.io/app/11
Great guide! Any update for Couchdb 2.0? Some information on Ubuntu and the required daemon scripts would be helpful.
thank you for guide.
Hi,
I can’t add the ppa on my droplet. I got the following message :
I tried that on a other ubuntu servers and it’s working. But it looks like my droplet can’ t resolve the PPA. I’ve tried several solutions already but the only thing left is the setup the proxy settings on the droplet, but I can’t find anything on DigitalOcean about a default proxy. Could you help me out ?
Thanks for this. I have been meaning to upgrade from 1.5 to 1.6.1 for ages - these steps were the clearest and simplest I found and worked right first time. Really appreciate it.