What is Apache CouchDB?

Apache CouchDB is a free, open-source database server which employs the same Couch Replication Protocol that Tap Forms uses to sync with IBM Cloudant. This means that Tap Forms is able to sync with your own server hosted in your own home or office without incurring the expense of an outside cloud based sync service.

Where can I get CouchDB?

Apache CouchDB can be downloaded from the following location:

http://couchdb.apache.org

Installing CouchDB

This topic will guide you through installing and setting up Apache CouchDB on a Mac. For other platforms, see the Apache CouchDB website for help.

  1. On the Apache CouchDB website, click the Download button at the top of the page.
  2. Click on the button to download CouchDB for Mac OS X (10.10+)
  3. In the Finder, double-click on the Apache-CouchDB ZIP file to uncompress it.
  4. Drag the Apache CouchDB.app file into your Applications folder.

Setup

  1. Run the Apache CouchDB application.
  2. Open up the CouchDB admin web page. It should launch your web browser and take you to the admin page automatically. You may recognize it because it looks very similar to the IBM Cloudant Dashboard. If it doesn’t launch, you can select Open Admin Console from the CouchDB menu that will display in your menubar.
  3. Verify the install by clicking on Verify, then Verify Installation. You should see checkmarks next to each entry.
  4. Click on Admin Party! then create an admin account.
  5. Click the Create Admins button to do that. Then give the admin a username and password.
  6. Click the Save button when done.

To create non-admin regular users

It’s not as straightforward to create a regular user with CouchDB. We’re not sure why they don’t have a proper interface for creating regular users, but it’s simple enough when you know how.

  1. Click on the Databases button in the CouchDB admin page.
  2. Click on the _users database. If the _users database does not exist yet, make sure you went through the Setup process first.
  3. Click the (+) button and then select the New doc function. A new record will be created in the _users table for you with a default value.
  4. Remove the default value.
  5. Copy and paste in the following code (including the curly braces) into the record.
  6. Replace username in both spots with the username you want to create. Don’t use any special characters in the username. Just letters and numbers. No spaces or punctuation.
  7. Replace plaintext_password with a proper password.
{
    "_id": "org.couchdb.user:username",
    "name": "username",
    "type": "user",
    "roles": [],
    "password": "plaintext_password"
}
  1. Click the Create Document button when you’re done. The password will automatically be encoded into a more secure derived_key and salt format when the document is created. This means anyone looking at the _users database will not be able to tell what the password is.

Configure CouchDB for Single Node Setup

CouchDB can be used in a single-node and cluster setup configuration. A single-node CouchDB installation is what most users will be using. For more advanced setups, consult the online documentation at https://docs.couchdb.org/en/stable/

  1. Click the Setup button. You will be asked to set up CouchDB as a single-node instance or set up a cluster.
  2. Click the Single-Node-Setup button. You will be asked for an admin username and password. Choose them well and remember them. You can also bind CouchDB to a public port, so it is accessible within your LAN or to the public.

Once you’ve done this you will be able to connect to your new CouchDB server from within Tap Forms running on other devices.

Setup Tap Forms 5 for Mac

  1. Launch Tap Forms and open the document you want to sync.
  2. Click Preferences under the Tap Forms menu.
  3. Click the Sync tab.
  4. Click the Cloudant & CouchDB button.
  5. Click the Service Provider popup button and choose Apache CouchDB.
  6. Enter the IP address of your CouchDB server in this format: http://127.0.0.1:5984. If you’re running your server on the same computer that Tap Forms is running on, use the IP address 127.0.0.1. Don’t forget to add a : followed by the port number 5984 after the IP address. If your CouchDB database is on a different server, then use that server’s IP address instead.
  1. Click on the Auto-Sync checkbox to enable automatic syncing.
  2. Click the Sign In button to sign-in to your new CouchDB server. The sync process will now begin.

Setup Tap Forms 5 for iOS (for local area network syncing only)

  1. Launch Tap Forms on your iOS device and open the document you want to sync.
  2. Tap the Tools tab.
  3. Tap the Sync Settings function.
  4. Tap the far right Cloud button.
  5. Tap CouchDB next to the Cloud Service option.
  6. Tap the Server field and enter the IP address of your CouchDB server in this format: http://0.0.0.0:5984. Replace the 0.0.0.0 with the actual IP address of your own CouchDB server. Don’t forget to add a : followed by the port number 5984 after the IP address.
  7. Tap Auto-Sync to enable the Auto-Sync function.
  8. Tap the Sign In button to sign-in to your database. The sync process will now begin.

Your Mac and iOS devices should now be syncing to your CouchDB server. There’s nothing more you need to do.

Optional, but highly recommended: Configure CouchDB to accept SSL secure connections

Configuring CouchDB to use SSL connections is more complicated. See the following page in the CouchDB documentation for more information:

How Do I Configure SSL (HTTPS) in CouchDB?

If you’re running your own CouchDB server on your own network or even on the same Mac you run Tap Forms on, then you can generate a Self Signed SSL Certificate to enable secure connections to the CouchDB server. However, to be truly secure you should obtain an SSL certificate from a valid Certificate Authority.

Here’s how you generate a Self Signed Certificate:

  1. Launch the Terminal application
  2. Generate a private key by copying and pasting the following line into the Terminal application window. Press the Return key after every line you copy and paste.
openssl genrsa -out couchdb.key 2048
  1. Generate a certificate signing request
openssl req -new -key couchdb.key -out couchdb.csr
  1. After the above command is entered, your Mac will ask you a series of questions. Here’s an example:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: CA
State or Province Name (full name) [Some-State]: Alberta
Locality Name (e.g., city) []: Calgary
Organization Name (e.g., company) [Internet Widgits Pty Ltd]: Tap Zapp Software Inc.
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []: voyager.local
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

The most important part of the above questions is the Common Name value. Since my computer is called Voyager, I put in voyager.local for the Common Name setting. You can find out what your computer name is by launching the System Preferences application and clicking on the Sharing preferences panel button. The value you’re looking for is right beneath the Computer Name setting where it says Computers on your local network can access your computer at: Voyager.local

  1. Create the self signed certificate using this shell script:
#!/bin/bash
# Set abort on error and trace.
set -e
set -x
# Use short hostname and append '.local' to get name
# Change this if you want to use another hostname.
HOSTNAME=$(hostname -s).local
# Delete CouchDB files
rm -rf couchdb*
# Create new key
openssl genrsa -out couchdb.key 2048
# Create new CSR
COUNTRY="Your Country Code e.g. US, CA, DE, etc."
STATE="Your State"
CITY="Your City"
ORGNAME="Your Organization Name"
openssl req -new -key couchdb.key -out couchdb.csr  -subj "/C=$COUNTRY/ST=$STATE/L=$CITY/O=$ORGNAME/CN=$HOSTNAME"
# Create new cert
openssl x509 -req -sha256 -days 735 -in couchdb.csr -out couchdb.crt -signkey couchdb.key -extfile <(printf "extendedKeyUsage = serverAuth \n subjectAltName=DNS:$HOSTNAME \n basicConstraints = CA:TRUE")

Set the COUNTRY, STATE, CITY, and ORGNAME variables to your own information.

  1. Copy the couchdb.key and couchdb.crt files to a location where CouchDB can find them.

Configure settings in CouchDB

  1. Back in the CouchDB admin webpage (Fauxton) on your computer, click the Configuration button.
  2. Click the Add Option button.
  3. Enter in the following options:
Section ssl
Name cert_file
Value /Path/to/couchdb.crt
Section ssl
Name key_file
Value /Path/to/couchdb.key

I found that when following the above instructions, I had to add a couple of more settings to prevent CouchDB from failing to startup after I edited the configuration.

Section ssl
Name ciphers
Value undefined
Section ssl
Name secure_renegotiate
Value undefined
Section ssl
Name tls_versions
Value undefined

Optional settings to protect access to some basic functions that return information about your CouchDB installation, such as the list of database names.

Section chttpd
Name require_valid_user
Value true
Section couch_httpd_auth
Name require_valid_user
Value true

There may be more appropriate values, but this worked for me.

The last setting must be added inside the following file (for CouchDB 2.1.1):

/Users/[your username]/Library/Preferences/couchdb2-local.ini

[daemons]
httpsd = {chttpd, start_link, [https]}

Once you’ve got your SSL certificate and key all setup and configured, you can use the name of your machine instead of the IP address inside Tap Forms. For the above example, I would use https://voyager.local:6984 to connect because Voyager is the name of my MacBook Pro.

To connect from iOS to your CouchDB server over SSL

Before you can connect to your CouchDB server using the name of your server (e.g. https://voyager.local:6984), you must first install the couchdb.crt file on your iOS device.

To install the SSL certificate on your iOS devices:

  1. Email the couchdb.crt file from your Mac to your iOS devices.
  2. Tap on it in the Apple Mail app.
  3. The Settings app will launch and you will be taken to the Install Profile screen.
  4. Follow all the prompts to install the certificate on your device. There’s lots of taps. You may be asked to enter your device password at some point.
  5. Go to Settings > General > About > Certificate Trust Settings.
  6. Tap on Enable Full Trust For Root Certificates to enable it for your certificate.

The certificate will show up in the Settings app under General > Profiles. You may have other profiles there, but the one for your CouchDB server that’s using a self signed SSL certificate will have the name of your server. In my case that’s voyager.local.

Now you can use https://voyager.local:6984 for the server name on the Apache CouchDB sync settings screen in Tap Forms 5. Use your own server name of course.

To connect from another Mac to your CouchDB server using SSL

  1. Copy the couchdb.crt file to all your Macs.
  2. Double-click on the couchdb.crt file in the Finder. It will launch The Keychain Access application and install it there for you.
  3. Double-click on your certificate in the Keychain Access application. A window with the certificate information will appear.
  4. Click on the triangle at the top to expand the Trust section.
  5. Select the Always Trust option next to When using this certificate.

To connect to your CouchDB server from the Internet

The above instructions help you to install and connect to a CouchDB server running on a Mac in your local network. If you want to be able to connect to your CouchDB server from the Internet, you’ll need to do a few things.

  1. Open a hole in your firewall to allow traffic on port 6984 to be routed to your Mac running Apache CouchDB. How you do this will vary depending on what kind of Internet router you have.
  2. Create a new SSL Certificate so it uses a fully qualified domain name. E.g. couchdb.yourcompany.com. You can either generate another self signed certificate or purchase an SSL certificate from a trusted authority, such as GoDaddy.
  3. Configure a DNS service to resolve couchdb.yourcompany.com to the IP address of your network. If you have a dynamic IP address provided by your ISP, you can use a free service like http://freeddns.noip.com
  4. Configure Tap Forms to connect to https://couchdb.yourcompany.com:6984 (use whatever DNS name you’ve given your server).
Last modified: Feb 05, 2024

Need more help with this?
Don’t hesitate to contact us here.

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.