CouchDraw

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!

<p align="center"> <img src="media/snake.gif" /> </p>

Table of Contents

1. Overview
2. Requirements
3. Getting Started
   1. Mobile
   2. Sync Gateway
   3. Couchbase Server
4. Configuring Couchbase Server for Sync Gateway
   1. Create a bucket
   2. Create a user
5. Starting Sync Gateway
6. Mobile Solution Architecture
7. Running the solution
8. Support and Contribution

Overview <a name="overview"></a>

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.

Requirements <a name="requirements"></a>

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

Getting Started <a name="getting-started"></a>

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:

1. Pull down this repository.
2. Install Sync Gateway
3. Install Couchbase Server
4. Configure Couchbase Server
5. Start Sync Gateway
6. Build and run the app

Mobile <a name="installation-mobile"></a>

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

• Couchbase.Lite
• Couchbase.Lite.Mapping
• SkiaSharp
• Robo.Mvvm

Couchbase Sync Gateway <a name="installation-sg"></a>

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.

Installation

Download the latest Sync Gateway 2.x installer from Downloads page. Be sure to select the "Mobile" tab.

Settings

To learn more about how to modify the Sync Gateway configuration file please see the documentation here.

Couchbase Server <a name="installation-cbs"></a>

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.

Installation

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.

Starting Couchbase Server

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.

Accessing Couchbase Server

Couchbase Server can be accessed using

• CLI
• API
• An administration (web) portal

Configuring Couchbase Server for Sync Gateway <a name="configure-cbs"></a>

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.

Create a bucket <a name="create-bucket"></a>

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:

1. Within the Couchbase Server admin portal click "Buckets", located on the left hand navigation menu.

   <img src="media/buckets.png" width="200px" />

2. Click "Add Bucket".

   <img src="media/add_bucket.png" width="200px" />

3. Fill in the details with the following.

   <img src="media/add_bucket_dialog.png" width="600px" />

   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.

Create a user <a name="create-user"></a>

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.

1. Click "Security", located on the left hand navigation menu.

   <img src="media/security.png" width="200px" />

2. Click "Add User"

   <img src="media/add_user.png" width="200px" />

3. 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.
   <img src="media/add_user_dialog.png" width="600px" />

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

Starting Sync Gateway <a name="start-sg"></a>

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

Note: "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.

<img src="media/indexes.png" width="600px" />

Mobile Solution Architecture <a name="mobile-architecture"></a>

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:

1. CouchDraw: The main Xamarin.Forms project.
2. CouchDraw.Core: A .NET Standard project containing ViewModels and Repository interfaces.
3. CouchDraw.Models: