Introduction
CouchDB is one of the most widely used and versatile NoSQL database management systems. Its perfect when you need to store database entries as flexible objects rather than entries following a rigid schema. Stack Harbor has made it easy for you to get started with CouchDB and its built-in web GUI using our turnkey Stacks.
Accessing Your Application
Once your Stack is built, you can verify that the installation proceeded correctly by using SSH to log into the machine and using CouchDB’s REST API to perform a simple GET request on the DB server. If you don’t already know how to SSH into your machine, we’ve written a detailed tutorial to help you get started.
Once you’ve SSHed into your machine, run the following command on your machine:
curl localhost:5984
cURL is a Linux tool that allows you to perform standard HTTP requests (GET, POST, PUT, DELETE) to a server. CouchDB exposes an HTTP API, so this command performs a simple GET request to the server. If the installation proceeded correctly, you should be returned with some JSON specifying CouchDB version, a unique UUID, the host operating system, and some other metadata regarding your CouchDB installation. When working with applications that will interact with your CouchDB server, it will be helpful to use the REST API that comes packaged with CouchDB. However, its not so useful when you’re just exploring your data and manually adding data. That’s where Futon, the prepackaged web GUI for CouchDB, comes into the picture. Since you’re running CouchDB remotely on our cloud servers, you won’t be able to access the GUI from your local computer using your browser since this functionality is disabled by default. We’ll show you how to set up an SSH tunnel so that all traffic on the CouchDB port on your Stack will be forwarded to your local machine. Run the following command in your terminal locally (not while logged into your Stack).
ssh -L 5984:127.0.0.1:5984 root@your_stack_ip_address
The -L flag tells the SSH daemon to forward traffic from the specified bind address and port on your remote machine to port 5984 locally. Now, if you open your browser and go to http://localhost:5984/_utils/, you’ll be prompted with the Futon interface.
Final Words
Congratulations! You have a working installation of CouchDB and Futon on your Stack! We’ve shown you how to interact with the REST API exposed by CouchDB as well as how to forward traffic on your Stack to your local machine in order to access the web GUI securely over an SSH connection. By default, any user who reaches the Futon interface is an admin user — we recommend you set up an authenticated user for security purposes. You can perform this action by looking to the bottom-right of web interface and click on the ‘Everyone is an admin. Fix This’ link. Additionally, the Futon interface has a ‘Verify Installation’ feature that you can use to further verify that there were no hiccups during the installation process. Finally, you can read more about CouchDB and Futon using the links to the documentation provided on the web GUI. From all of us at Stack Harbor, ahoy!