Configure Your App Services Trial (Mobile sync)

tutorial

Configure App Services to test out a mobile application with your trial database.

Capella App Services

Capella App Services is a fully managed application backend designed for mobile and edge applications. You can use Capella App Services with an embedded Couchbase Lite database in your applications.

With Capella App Services, you can:

Sync data between your buckets in Capella and any mobile or edge device.
Sync data directly between devices without a network connection to Capella App Services with Peer-to-Peer.
Authenticate and manage mobile and edge users through App Services Endpoints.

Prerequisites

You deployed a Couchbase Capella free trial database. For more information, see Deploy Your Database.
Your trial database has the travel-sample bucket. For more information, see Import Data with the Capella UI.
You deployed your App Services trial. For more information, see Deploy Your App Services Trial.
You have a REST Client, such as Postman or HTTPie installed and configured.

Create an App Endpoint for Your Trial App Service

To create an App Endpoint:

Go to App Services and select the App Service you want to create an endpoint for.
Go to App Endpoints and click Create App Endpoint.
In the App Endpoint Name field, enter travel-sample-appservice.
In the Linked Bucket list, select travel-sample.
(Optional) Select Enable Delta Sync to only sync parts of the document that have changed for the app users. By default, the entire document is synced.
(Optional) Select Enable Import Filter to filter the server documents processed by the App Endpoint. By default, all server documents are imported.
Click Create App Endpoint.

Until it deploys, the App Endpoint’s status shows as Offline.

Configure the App Endpoint with an Access Control Policy

To configure access control for your new App Endpoint:

Go to App Endpoints and select travel-sample-appservice.
Go to Security Access and Validation.

In the text editor, replace the existing text with the following JavaScript code:

function (doc, oldDoc, meta) {
  if (doc.channels) {
      // If channels list is specified in document, assign doc to the channels
     channel(doc.channels);
  }
  else {
    // assign to public channel (which is accessible to all users)
    channel ("!")
  }
}

Click Save.
In the Changes being applied… dialog, click OK.
Click Resume app endpoint.
In the App Endpoint set to Resume dialog, click OK.

Create an App Role for the App Endpoint

To add an App Role for the App Endpoint:

Go to Security App Roles.
Click Create App Role.
In the Create App Role dialog, do the following:
1. In the App Role Name field, enter admin.
2. In the Admin Channels field, enter an asterix (*) and press Enter.
3. Click Create App Role.

Create an App User for the App Endpoint

To create a user for the App Endpoint:

Go to Security App Users.
Click Create App User.
In the Create App User page, do the following:
1. In the App Username field, enter a username for the new app user.
2. In the Password field, enter a password for the new app user.
3. In the Admin Channels field, enter an asterix (*) and press Enter.
4. In the Admin App Roles field, enter admin and press Enter.
5. Click Create App User.

Access the App Endpoint with the App Services REST API

You can use a REST client to connect to the App Services Public REST API.

To retrieve a document from the travel-sample bucket through the App Services Public REST API:

Go to Connect.
Next to the Public Connection field, click Copy.
In your REST Client, create a GET request.
Paste the Public Connection URL and change wss to https.
Add /airline_10 to the end of the URL. Your URL should look similar to https://123456789.apps.capella.com:4984/travel-sample-appservice/airline_10.
Select Basic Authentication.
Enter the username and password for the App User you created.
Send the GET request to receive the contents of the document airline_10 as the response.

For more information about the Public REST API, see Public REST API.

Connect a Couchbase Lite App to the Capella App Service Endpoint

Couchbase Lite is an embedded database. You can use it to embed data processing and storage in applications that run on mobile and IoT devices, allowing apps to locally store and access data without an Internet connection.

Couchbase Lite embedded apps can connect to App Endpoints and sync data with each other and the Couchbase Capella backend over a websockets-based data sync protocol.

To connect Couchbase Lite to your App Endpoint:

Go to App Services and select an App Service.
Go to App Endpoints and select travel-sample-appservice.
Go to Connect.
Next to the Public Connection field, click Copy.
Use a Couchbase Lite sample application to connect to your App Service:
- Swift (iOS, macOS): Replace the URLEndpoint in the sample code with your App Endpoint Public Connection URL.
- Kotlin (Android): Replace the URLEndpoint in the sample code with your App Endpoint Public Connection URL.
- Java (Android): Replace the URLEndpoint in the sample code with your App Endpoint Public Connection URL.
- .Net (Desktop, Xamarin): Replace the URLEndpoint in the sample code with your App Endpoint Public Connection URL.
- Java (Desktop): Replace the URLEndpoint in the sample code with your App Endpoint Public Connection URL.
- C (Desktop, Mobile, Embedded): Replace the CBLEndpoint_CreateWithURL in the sample code with your App Endpoint Public Connection URL.

(Optional) Administer App Users with the App Services REST API

You can use the App Services Admin REST API to add new users and return a list of users.

To use the App Services Admin REST API:

Add an allowed IP address and create an admin credential
Connect to the endpoint
Add an App Services user

Add an Allowed IP and Create an Admin Credential

To add an allowed IP address and create an admin credential:

Go to App Services and select an App Service.
Go to App Endpoints and click travel-sample-appservice.
Go to Connect.
Under Allowed IP Addresses, click Go to Allowed IP Addresses.
Click Add Allowed IP Address.
In the Add Allowed IP page, you can either:
- Click Add Current IP Address to populate the Allowed IP / CIDR Block field with your IP address.
- Click Allow Access from Anywhere to allow any IP address to connect to your database.
- Enter an IP address or IP address range in CIDR notation in the Allowed IP / CIDR Block field.
Click Add Allowed IP.
Go to App Endpoints and click travel-sample-appservice.
Go to Connect.
Under Admin and Metrics Credentials, click Manage Credentials.
Click Create Admin Credential.
In the Create Admin Credential page, do the following:
1. In the Username field, enter admin.
2. In the Password field, enter a password for the admin credential.
3. Click Create Admin Credential.

Connect to the App Services Admin REST API

You can use a REST client to connect to the App Services Admin REST API:

Go to App Services and select an App Service.
Go to App Endpoints and click travel-sample-appservice.
Go to Connect.
Next to the Public Connection field, click Copy.
In your REST client, create a GET request.
Paste the Admin Connection URL.
Add /_user to the end of the URL. Your URL should look similar to https://123456789.apps.capella.com:4985/travel-sample-appservice/_user/.
Select Basic Authentication.
Enter the admin credential you created.
Send the GET request to receive the App User you created earlier.

Add an App Services User

To add a new App Services User with the App Services Admin REST API:

In your REST client, create a POST request.
Paste the Admin Connection URL.
Add /_user to the end of the URL. Your URL should look similar to https://123456789.apps.capella.com:4985/travel-sample-appservice/_user/.
Select Basic Authentication.
Enter the admin credential you created.

In the request body, add the following JSON code:

{
  "name": "demo2@example.com",
  "password": "password",
  "admin_channels": [
    "string"
  ],
  "disabled": false
}

Send the POST request.
Go to App Services and select an App Service.
Go to App Endpoints and click travel-sample-appservice.
Go to Security App Users.
In the Capella UI, return to the App Endpoints page.
Click travel-sample-appservice.
Go to Security App Users.

The POST request adds the new user demo2@example.com.

For more information about the Admin REST API, see Admin REST API.