Apache CouchDB Sync

!This is an advanced topic which describes how to install and setup your own CouchDB server. Running your own CouchDB server will allow you to have your own sync solution within your own network without incurring the limitations of Nearby sync. You won’t have to have the same document opened at the same time for sync to function. All changes made on all your devices will be stored in your Apache CouchDB server. The primary audience for this sync solution is anyone who doesn’t want their data to be stored on a server outside their home or office location.

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.

*If you see an entry for bind address, make sure it’s set to 0.0.0.0 or else you won’t be able to connect to it from other devices.

*Only admins can create databases. Because only admins can create databases, if you try to sign in with a regular user account and the database hasn’t been created in CouchDB yet, Tap Forms will display an error indicating the database does not exist. You can temporarily sign in as an admin to create the database or you can use the CouchDB admin console to create a database with the same database ID value that you see on the Sync Settings screen in Tap Forms. You’ll know the ID number when you see it since it starts with “db-” and has a bunch of random letters and numbers after it. Copy that to the clipboard and paste it into the CouchDB admin console when creating your database.

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"
}

8. 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.

!You will need to use http instead of https if you’re connecting to an IP address. If you would prefer to connect to a named server, for example https://couchdb.mycompany.com:6984 then you’ll need to make sure you use https and you have the appropriate SSL secure certificate installed on that server. The default port number for https connections is 6984. By using an IP address instead of a named server, you can avoid needing to setup an SSL certificate. However, syncing between Tap Forms and your CouchDB server will NOT be secure. It’s preferable to setup the appropriate SSL certificates on your CouchDB server so you can sync securely.

7. Click on the Auto-Sync checkbox to enable automatic syncing.
8. 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

3. Generate a certificate signing request

openssl req -new -key couchdb.key -out couchdb.csr

4. 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

5. 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.

6. 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

!You will not be able to logout of the admin console when you add the above setting because your browser will log you in again if it remembers the username and password.

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]}

*If CouchDB gets stuck trying to launch over and over again, you can find the configuration file in this location on your drive and delete it:
/Users/[your username]/Library/Preferences/couchdb2-local.ini
You will need to quit CouchDB first before you delete that file. Click the CouchDB menu in the menubar and select the Quit Apache CouchDB command.

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.

*Please note that to connect to a CouchDB over SSL, you need to use port number 6984. Although you can actually change that in the configuration in the CouchDB admin interface.

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).

!If you want to use the same server address when connecting to CouchDB on both the inside and outside of your local area network, you’ll need to configure a DNS server on your local network to return the local IP address of your CouchDB server (e.g. 192.168.0.5). This is very useful if you use MacBooks and iOS devices both inside and outside of your local area network. Your Macs and iOS devices will also have to be configured to use your local network’s DNS servers.

Copyright 2016, Tap Zapp Software Inc. All Rights Reserved.