CouchDraw combines the power of SkiaSharp, Xamarin, and Couchbase to create a fully synchronized canvas across devices and platforms. This readme will walk you through the steps for getting this app up and running (locally) in under 15 minutes!
- Overview
- Requirements
- Getting Started
- Configuring Couchbase Server for Sync Gateway
- Starting Sync Gateway
- Mobile Solution Architecture
- Running the solution
- Support and Contribution
CouchDraw is a simple synchronized drawing app powered by:
- An embedded Couchbase Lite database.
- The synchronization engine of Sync Gateway
- A distributed Couchbase Server database.
- The cross-platform mobile solution capabilities of Xamarin.
This project assumes familiarity with building Xamarin, more specifically Xamarin.Forms, apps using C# and XAML.
- iOS (Xcode 9+)
- Android (SDK 21+)
- git (Optional) - this is required if you would prefer to pull the source code from GitHub repo.
- Create a free github account if you don’t already have one
- git can be downloaded from git-scm.org
CouchDraw is a made of three parts:
- A Xamarin.Forms cross-platform mobile solution.
- Couchbase Sync Gateway that facilitates the data synchronization between app instances.
- Couchbase Server which functions as the distributed database that houses CouchDraw's canvas data.
Before jumping into the details here's TLDR; steps for getting this app up and running:
- Pull down this repository.
- Install Sync Gateway
- Install Couchbase Server
- Configure Couchbase Server
- Start Sync Gateway
- Build and run the app
After pulling down this repository no additional installation is needed to build the solution file.
Within the solution there are several notable Nuget packages that have been referenced and will be installed upon opening the solution within an IDE (i.e. Visual Studio).
Sync Gateway is the synchronization server in a Couchbase Mobile deployment.
Sync Gateway is designed to provide data synchronization for large-scale interactive web, mobile, and IoT applications. Commonly used features include:
-
User authentication, ensuring that only authorized users can connect to Sync Gateway (see user authentication guide).
-
Access Control, guaranteeing that only relevant documents are synced. Sync Gateway accomplishes this by examining document and applying business logic to decide whether to assign the documents to channels. Access control and ensuring that only relevant documents are synced are achieved through the use of channels and the Sync Function.
Download the latest Sync Gateway 2.x installer from Downloads page. Be sure to select the "Mobile" tab.
To learn more about how to modify the Sync Gateway configuration file please see the documentation here.
Couchbase Server is an open source, distributed, NoSQL document-oriented engagement database. It exposes a fast key-value store with managed cache for sub-millisecond data operations, purpose-built indexers for fast queries and a powerful query engine for executing SQL-like queries.
To install Couchbase Server please follow the instructions here.
Note: I advise installing Couchbase Server manually to start. If you install using Docker you will need to ensure that both Sync Gateway and Couchbase Server are running on the same Docker Host, and then you'll need to configure accordingly. You can find more instructions using Docker here.
Once Couchbase Server has been installed simply navigate to where it has been installed and start "Couchbase Server".
To start Couchbase Server using Docker please see the documentation here.
Couchbase Server can be accessed using
Once Couchbase Server has been started navigate to the admin portal at http://localhost:8091.
Note: Because CouchDraw is a simple demo app you're only going to be using one node within a single cluster.
Couchbase uses buckets to group collections of keys and values logically. Simply put, documents are stored in buckets, and you're going to need a bucket to store CouchDraw documents in.
To create a bucket that can be accessed by Sync Gateway and the embedded Couchbase Lite database do the following:
-
Within the Couchbase Server admin portal click "Buckets", located on the left hand navigation menu.
-
Click "Add Bucket".
-
Fill in the details with the following.
Note: The Sync Gateway JSON configuration file that is included in the repo currently has a username of "couchdraw_user" and a password of "password". The key here is that whatever is in the Sync Gateway configuration file needs to be the same as the user you create in Couchbase Server in order to allow application access.
In order for Sync Gateway to access the "couchdraw" bucket we need to create a user for it to use with the appropriate permissions. To do that you'll need to create a new users with the following steps.
-
Click "Security", located on the left hand navigation menu.
-
Click "Add User"
-
Once the dialog is displayed, do the following:
- Add a username.
- Add a password.
- Select "Read-Only Admin" access under the "Administration & Global Roles" section.
- Select "Application Access" under the "couchdraw" section.
Note: The Sync Gateway JSON configuration file that is included in the repo currently has a username of "couchdraw_user" and a password of "password". The key here is that whatever is in the Sync Gateway configuration file needs to be the same as the user you create in Couchbase Server in order to allow application access. \
After Couchbase Server is running and configured for CouchDraw you'll need to start Sync Gateway. To start Sync Gateway execute the following command.
~/where-you-installed-sync-gateway/couchbase-sync-gateway/bin/sync_gateway ~/path/to/basic-sync-function.jsonNote: "basic-sync-function.json" is included within the repo here.
When Sync Gateway initially starts and accesses Couchbase Server it will create a variety of indexes on the "couchdraw" bucket.
As mentioned before, CouchDraw is a Xamarin.Forms solution. Now that you've pulled down the project you can open it in your favorite IDE. You'll notice that the solution contains six projects:
- CouchDraw: The main Xamarin.Forms project.
- CouchDraw.Core: A .NET Standard project containing ViewModels and Repository interfaces.
- CouchDraw.Models: A .NET Standard project that containing domain models.
- CouchDraw.Repositories: A .NET Standard project containing the repositories and database managers used for integrating with Couchbase Lite and Sync Gateway.
- CouchDraw.iOS: The Xamarin.iOS platform project.
- CouchDraw.Android: The Xamarin.Android platform project.
Now that Couchbase Server has been configured and Sync Gateway is running you're ready to build and run the app!
By default the app is set up to run locally, but it can certainly be configured to point to external instance of Sync Gateway and Couchbase Server as well.
The connection information for Sync Gateway resides in DatabaseManager.cs.
// Note: User 'localhost' or '127.0.0.1' when using a simulator
readonly Uri _remoteSyncUrl = new Uri("ws://localhost:4984");
// Note: Use '10.0.2.2' when using an emulator
//readonly Uri _remoteSyncUrl = new Uri("ws://10.0.2.2:4984");
Thanks so much for taking a look at CouchDraw! This is a very simple example, and there's a lot of potential for customization. Please feel free to contribute to this project. Here are a couple of ideas for features to add:
- Replacing the color buttons with a range slider for color selection.
- Adding the ability to change the line thickness.
- Adding the ability to erase lines that have been drawn.
If you have any questions, comments, or would like to contribute to this projects please reach out to me directly at robert.hedgpeth@couchbase.com or on Twitter.