Bitnami CouchDB Installer

NOTE: Before running the commands shown on this page, you should load the Bitnami stack environment by executing the installdir/use_APPNAME script (Linux and Mac OS X) or by clicking the shortcut in the Start Menu under "Start -> Bitnami APPNAME Stack -> Application console" (Windows). Learn more.
NOTE: When running the commands shown on this page, replace the installdir placeholder with the full installation directory for your Bitnami stack.

Description

CouchDB is an open source NoSQL database that stores your data with JSON documents, which you can access via HTTP. It allows you to index, combine, and transform your documents with JavaScript.

First steps with the Bitnami CouchDB Stack

Welcome to your new Bitnami application! Here are a few questions (and answers!) you might need when first starting with your application.

What are the system requirements?

Before you download and install your application, check that your system meets these requirements.

How do I install the Bitnami CouchDB Stack?

Windows, OS X and Linux installer
  • Download the executable file for the Bitnami CouchDB Stack from the Bitnami website.

  • Run the downloaded file:

    • On Linux, give the installer executable permissions and run the installation file in the console.
    • On other platforms, double-click the installer and follow the instructions shown.

Check the FAQ instructions on how to download and install a Bitnami Stack for more details.

The application will be installed to the following default directories:

Operating System Directory
Windows C:\Bitnami\APPNAME-VERSION
Mac OS X /Applications/APPNAME-VERSION
Linux /opt/APPNAME-VERSION (running as root user)
OS X VM
  • Download the OS X VM file for the Bitnami CouchDB Stack from the Bitnami website.
  • Begin the installation process by double-clicking the image file and dragging the WordPress OS X VM icon to the Applications folder.
  • Launch the VM by double-clicking the icon in the Applications folder.

What credentials do I need?

You need application credentials, consisting of a username and password. These credentials allow you to log in to your new Bitnami application.

What is the administrator username set for me to log in to the application for the first time?

  • For Windows, Linux and OS X installers, the username was configured by you when you first installed the application.
  • For OS X VMs, the username can be obtained by clicking the Bitnami badge at the bottom right corner of the application welcome page.

What is the administrator password?

  • For Windows, Linux and OS X installers, the password was configured by you when you first installed the application.
  • For OS X VMs, the password can be obtained by clicking the Bitnami badge at the bottom right corner of the application welcome page.

How to start or stop the services?

Linux

Bitnami native installers include a graphical tool to manage services. This tool is named manager-linux-x64.run on Linux and is located in the installation directory. To use this tool, double-click the file and then use the graphical interface to start, stop or restart services. Server log messages can be checked in the "Server Events" tab.

Management tool

The native installer also includes a command-line script to start, stop and restart applications, named ctlscript.sh. This script can be found in the installation directory and accepts the options start, stop, restart, and status. To use it, log in to the server console and execute it following the examples below:

  • Call it without any service names to start all services:

      $ sudo installdir/ctlscript.sh start
    
  • Use it to restart a specific service only by passing the service name as argument - for example, mysql, postgresql or apache:

      $ sudo installdir/ctlscript.sh restart mysql
      $ sudo installdir/ctlscript.sh restart postgresql
      $ sudo installdir/ctlscript.sh restart apache
    
  • Obtain current status of all services:

      $ installdir/ctlscript.sh status
    

The list of available services varies depending on the required components for each application.

Mac OS X

Bitnami native installers include a graphical tool to manage services. This tool is named manager-osx on Mac OS X and is located in the installation directory. To use this tool, double-click the file and then use the graphical interface to start, stop or restart services. Server log messages can be checked in the "Server Events" tab.

Management tool

The native installer also includes a command-line script to start, stop and restart applications, named ctlscript.sh. This script can be found in the installation directory and accepts the options start, stop, restart, and status. To use it, log in to the server console and execute it following the examples below:

  • Call it without any service names to start all services:

    $ sudo installdir/ctlscript.sh start
    
  • Use it to restart a specific service only by passing the service name as argument - for example, mysql or apache:

     $ sudo installdir/ctlscript.sh restart mysql
     $ sudo installdir/ctlscript.sh restart apache
    
  • Obtain current status of all services:

     $ installdir/ctlscript.sh status
    

The list of available services varies depending on the required components for each application.

NOTE: If you are using the stack manager for Mac OS X-VM, please check the following blog post to learn how to manage services from its graphical tool.

Windows

Bitnami native installers include a graphical tool to manage services. This tool is named manager-windows.exe on Windows and is located in the installation directory. To use this tool, double-click the file and then use the graphical interface to start, stop or restart services. Server log messages can be checked in the "Server Events" tab.

Management tool

The Windows native installer creates shortcuts to start and stop services created in the Start Menu, under "Programs -> Bitnami APPNAME Stack -> Bitnami Service". Servers can also be managed from the Windows "Services" control panel. Services are named using the format APPNAMESERVICENAME, where APPNAME is a placeholder for the application name and SERVICENAME is a placeholder for the service name. For example, the native installer for the Bitnami WordPress Stack installs services named wordpressApache and wordpressMySQL.

These services will be automatically started during boot. To modify this behaviour, refer to the section on disabling services on Windows.

What is the default configuration of CouchDB?

The default access port for CouchDB's HTTP server is 5984. HTTPS is disabled and remote access is disabled by default.

How to connect to CouchDB from a different machine?

IMPORTANT: Bitnami Native Installers do not modify the firewall configuration of your computer, therefore the CouchDB ports could be open which is a significant security risk. You are strongly advised to close the CouchDB ports (refer to the FAQ for more information on this).

Assuming the CouchDB port is open for remote access, perform these additional steps:

  • Stop your CouchDB server and edit the installdir/couchdb/etc/local.ini file. Change the bind_address from 127.0.0.1 to 0.0.0.0:

      [chttpd]
      port = 5984
      bind_address = 0.0.0.0
      ...
    
      [httpd]
      bind_address = 0.0.0.0
      ...
    
  • Restart your server for the changes to take effect.

      $ sudo installdir/ctlscript.sh restart couchdb
    

You should now be able to connect to the CouchDB server from a different machine using the server's IP address and receive a welcome message. This is shown in the example command and output below:

$ curl http://SERVER_URL:5984/
{"couchdb":"Welcome","version":"2.1.1","features":["scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

How to change the CouchDB admin password?

You can modify the CouchDB admin password with these steps:

  • Stop your server.

     $ sudo installdir/ctlscript.sh stop couchdb
    
  • Edit your installdir/couchdb/etc/local.ini configuration file, editing the respective admin password to what you want, in the [admin] section. For example:

     admin = my_new_password
    
  • CouchDB will take care of hashing your password, so the only thing you need is to start your server again.

     $ sudo installdir/ctlscript.sh restart couchdb
    

How to enable SSL (for HTTPS) on CouchDB?

You can enable SSL on CouchDB using these steps:

  • Stop CouchDB.

     $ sudo installdir/ctlscript.sh stop couchdb
    
  • Edit your installdir/couchdb/etc/local.ini file and edit the [daemons] section so that the line activating the httpsd daemon is uncommented.

     [daemons]
     httpsd =  {couch_httpd, start_link, [https]}
    
  • Within the same file, make sure your [ssl] section includes at least the following lines uncommented:

     [ssl]
     port = 6984
     cert_file = installdir/couchdb/conf/server.crt
     key_file = installdir/couchdb/conf/server.key
    

    The certificates Bitnami includes are self-signed so you might get a warning when trying to access your site. To avoid this warning, you should get new certificates signed by a Certificate Authority, and uncomment the following line:

     ;cacert_file = /full/path/to/cacertf
    
  • Open the CouchDB HTTPS port in the server firewall. For more information, refer to the FAQ.

NOTE: Remember to change the bind_address from 127.0.0.1 to 0.0.0.0 if you want to connect to CouchDB from a different machine. Refer to these instructions for more information.
  • Finally, start your CouchDB server again and you will be able to access CouchDB over SSL at the selected port eg. at https://localhost:6984/.

     $ sudo installdir/ctlscript.sh restart couchdb
    

How to connect to Fauxton, the CouchDB management panel?

By default, CouchDB is configured to listen on the local interface only, so an SSH tunnel is needed to access it. Use port 5984 (the default CouchDB port) for both ends of your SSH tunnel. Follow these instructions to remotely connect safely and reliably.

Once your SSH tunnel is running, you can connect to Fauxton, CouchDB's management panel, by browsing to http://127.0.0.1:LOCAL_PORT/_utils/. To log in, use the username and password obtained from the server dashboard. Remember to replace LOCAL-PORT with the local port number specified during the SSH tunnel creation.

How to debug CouchDB errors?

To debug CouchDB's errors, use the log files at installdir/couchdb/var/log/couchdb/.

nativeInstaller