CouchChat demo for Couchbase Lite
CouchChat is a multi-user messaging app, essentially a primitive clone of the iOS Messages app. It illustrates how you can use Couchbase Lite in your mobile apps to share data across devices and among users. If you familiarize yourself with this code, you'll be ready to write your own multi-user interactive data driven applications on iOS.
There is a tour of the data model on the wiki.
There are three main components to the system:
- This app, which embeds Couchbase Lite for iOS.
- The Couchbase Sync Gateway, which runs on a server and handles the synchronization connections from mobile devices.
- Couchbase Server 2.0 for data storage. (For development this is optional; you can instead use a very simple built-in data store called Walrus.)
Couchbase Server should be deployed behind your firewall (like databases normally are), and then the Sync Gateway should be deployed where it can be accessed by mobile devices from the public internet, and it can reach Couchbase Server. Mobile devices connect to the Sync Gateway, which enforces access control and update validation policies.
Running this app
Install the submodules:
git submodule init git submodule update
Build/Install the CouchBase Lite framework
There are precompiled binary packages of Couchbase Lite, but they are currently (June 2013) not up to date, so the recommended way is to build the Couchbase Lite framework yourself, following the directions in its wiki.
Once it is built, copy the output
CouchbaseLite.framework into the the CouchChat repository's
Build and run the app
Now you can build and run your app in the simulator or on a connected iOS device.
After startup it will prompt you to login with Mozilla Persona. Once you are logged in, you can:
- Create a chat room
- Invite other users
- Send messages to users.
- Attach pictures to a message (or take a picture if your device has a camera.)
Any message in a chat room will show up on all devices that are subscribed to that room.
Running the PhoneGap version
For extra credit you can try running the HTML5 version of CouchChat against the same Sync Gateway database. The HTML5 version of the app is under development in our Couchbase Lite PhoneGap Kit repository.
Running your own server
If you want to run your own chat server rather than the default public one, you'll need to install the Couchbase Sync Gateway, configure it for chat, and update the iOS app to talk to it.
Install the Sync Gateway
Installation and configuration of the Sync Gateway is beyond the scope of this README. The Sync Gateway docs discuss installation. When you're done you'll be the proud owner of a
sync_gateway command-line tool.
Configure the gateway for chat
The CouchChat repo contains a configuration file for the gateway,
sync-gateway-config.json. Put the path to the config file on the command line when you launch the gateway.
This config file does not contain the public (or LAN) address that your iOS app will contact. The Gateway needs to be aware of that address in order for Persona authentication to work properly. You'll provide that address as a command line option. It should consist only of the root URL of the server, including the port but without any path or trailing slash.
So your launch command will look something like:
sync_gateway -personaOrigin="http://animal.local:4984" ~/code/CouchChat-iOS/sync-gateway-config.json
The example config file uses an in-memory Walrus bucket, so all your data will be lost when the Sync Gateway exits. To avoid this you can edit the
databases.sync_gateway.server property of the config file to point to an existing directory where you'd like to store your data. In production you should replace the
walrus: url with a URL to Couchbase Server's 8091 port.
Update the iOS app
Now edit the value of
AppDelegate.m to the public URL of your Sync Gateway's chat database. This should match the value of the
-personaOrigin command-line flag given to the Sync Gateway, but with the database name (default is
How the data flows
sync-gateway-config.json) determines how data flows between mobile devices, or it can throw an error if a given update is not allowed to proceed. Read the Sync Gateway documentation for more details.
Read the tour of the data model to learn how the sync function for CouchChat works.