Before we get started, we'll need to make sure that we have got Ubuntu 16.04 LTS Xenial in our machine or server as we are featuring CouchDB installation in Ubuntu 16.04 LTS Xenial. If we don't have one and planning to install Ubuntu 16.04, you can download it from the Official Ubuntu Download Page. Once we have our Ubuntu 16.04 ready to go, we'll first need to update the local repository index of the apt package manager. If we are accessing using root user, we don't need to enter sudo everytime we run the commands but as we are running a non-root user, we'll need to enter sudo at every command in order to access root privileges.
$ sudo apt-get update
Once the local repository of the apt package manager has been updated, we'll gonna upgrade the packages of our Ubuntu system using the following command.
$ sudo apt-get upgrade
Adding PPA Repository
Once we meet our pre-requisites, we'll move forward towards the installation of CouchDB and Futon. As we have Ubuntu PPA repository of Apache CouchDB maintained and updated by the CouchDB project and the communities, we'll gonna go for it. Installing CouchDB using PPA repository is the most easiest and simple method to install the official release of CouchDB. First of all, we'll need to make sure that we have installed the package named software-properties-common so that we can easily add the PPA repository in our Ubuntu machine. In order to install it, we'll need to execute the following command.
$ sudo apt-get install software-properties-common
Next, we'll gonna add the official CouchDB PPA repository using add-apt-repository command in the terminal.
$ sudo add-apt-repository ppa:couchdb/stable
Then, we'll need to update the local repository index of apt package manager as we have added new PPA repository above.
$ sudo apt-get update
Now, we'll go for the installation of CouchDB in our machine as all the above steps has been completed. In order to install CouchDB from the official PPA repository, we can now simply run the following apt-get command in our terminal. This will install couchdb with its required dependencies from their respective repositories.
$ sudo apt-get install couchdb
Fixing Ownership and Permission
As some files and directories are set under root user and group by default, it may be risky as per the security in the production, so its highly recommended to fix the permission. In order to fix the issue, we'll need to change the ownership of the files belonging to the couchdb user and group. As the new user and group for couchdb is already created by default during the installation process above, we'll no need to create another. In order to change the ownership, we'll simply need to run the following command.
$ sudo chown -R couchdb:couchdb /usr/bin/couchdb /etc/couchdb /usr/share/couchdb
Once done, we'll now need to fix the permission of those files and directories by executing the following.
$ sudo chmod -R 0770 /usr/bin/couchdb /etc/couchdb /usr/share/couchdb
Once all the steps above are done successfully, we'll now restart our CouchDB instance. In order to do so, as we are running Ubuntu 16.04 LTS Xenial and its shipped with systemd as the default init system, we'll need to run the following command.
$ sudo systemctl restart couchdb
In order to test if CouchDB is running fine or not, we can simply run the following command which will retrieve the information through curl.
$ curl localhost:5984
As CouchDB natively includes Futon, the web interface for CouchDB we can simply access it via our web browser. In order to do so, we'll first need to perform SSH tunneling as allowing Futon across the firewall currently may be dangerous as we haven't set a proper admin credentials. In order to setup SSH tunneling, we'll need to run the following command.
$ ssh -L 5984:127.0.0.1:5984 arun@ip-address
Note: Here we'll need to replace arun and ip-address with username and ip address of the server respectively.
Now, as we have successfully setup the SSH tunneling, we'll now access the web interface of CouchDB. To do so, we'll need to open a web browser and point it to http://localhost:5984 .
Then, in order to access the web application of Futon, we'll need to point to http://localhost:5984/_utils/index.html . Once done, we'll get access to the Futon Database Administration Panel in which we can perform different CouchDB database management activities.
As we don't require any login credentials to login to the Futon panel and as every account is an admin account in it, anyone accessing Futon has the ability to make changes to the database. So, first of all, we'll need to secure it by creating a new Admin account. To do so, we can simply click on Fix it link shown in the bottom of the right-sidebar.
Doing so will open a dialogue box allowing us to create a new admin account. Here, we'll need to enter the required username and password which we'll use further to login to Futon.
Now, in order to create a database, we'll need to login to Futon Control Panel using the username and password created above. Then, we'll click on Create Database button available on the top-left of the screen. Then, we'll be asked to enter a name for our new database to be created. Next, we can add new documents, edit, delete, update and save the documents via Futon easily.
Allowing External Access
If you need to make CouchDB accessible and available outside of our local network or our local machine, then we'll need to make sure that the above steps on securing Futon is completed. Then, we'll need to add 0.0.0.0 to the bind-address varilable in /etc/couchdb/local.ini file under [httpd] block. To do so, we'll need to login as root user and open the file using a text editor.
$ su root
# nano /etc/couchdb/local.ini
bind_address = 0.0.0.0
Here, we can customize our configurations according to our needs and requirements. Once done, we'll gonna save the file and exit the text editor. Once done, we can simply log out from the root user by executing exit command in the terminal.
Now, in order to apply the changes, we'll need to restart our CouchDB services using systemctl command.
$ sudo systemctl restart couchdb
As we are making our CouchDB available out of our local network, we'll also need to make sure that port 5984 is opened by the firewall program. As Ubuntu 16.04 LTS Xenial runs with systemd as the default init system, firewalld is most probably used as the firewall program.
$ sudo firewall-cmd --zone=public --add-port=5984/tcp --permanent
Once the port is added for public access, we'll need to a make sure that we reload the firewalld program.
$ sudo firewall-cmd --reload
Note: Allowing CouchDB accessible through the internet makes anyone able to add and access the documents and databases whereas they are unable to edit and delete the documents as we have already created an admin user above. So, its not recommended to allow CouchDB accessible externally, if we need access to it remotely, we can make use of SSH tunneling or allow a specific ip address to connect via iptables or firewall program.
Finally, we have easily and succesfully installed CouchDB with its web based interface Futon in our machine running Ubuntu 16.04 LTS Xenial. Documents and databases in CouchDB can be easily accessible by everyone so we'll need to make sure that our database is not accessible by public or untrusted people. We can even install it manually using the tarballs available in the official download page but as we are running Ubuntu 16.04 LTS Xenial, its pretty easy to install using the PPA repository. So, if you have any questions, suggestions, feedback please write them in the comment box below. Thank you ! Enjoy :-)
You might also like
Category: LINUX HOWTO