Skip to content

Latest commit

 

History

History
328 lines (236 loc) · 11.7 KB

Tutorial.adoc

File metadata and controls

328 lines (236 loc) · 11.7 KB
Raw

Couchbase Server High Availability and Disaster Recovery Lab

Table of Contents

This tutorial is intended to give a step-by-step series of exercises to get you up and running with Couchbase Server in a configuration that supports global high availability and disaster recovery. It includes supporting material in the form of an example application written in Java.

[N.B. In the following sections we will present sample output from commands. This is intended to give an idea of a typical response. The actual output will likely differ. Some output has been reduced for brevity.]

Section 1 - Installing and Configuring a Single Node Cluster

In this section we will walk through installing a new node of Couchbase Server from the Linux command line. In the end, you will have a functioning node suitable for doing key/value based document operations.

Lab Exercise 1.1 - Deploy a Single Node

In this exercise, we will deploy a single node of Couchbase Server. The instructions apply for Red Hat Enterprise Linux and CentOS Linux 7. For more details, or instructions to get started with other platforms, go to https://developer.couchbase.com/documentation/server/current/getting-started/start-here.html

  1. Open a command shell on your server.

  2. Verify pkgconfig is installed, or install it.

sudo yum install -y pkgconfig

The command should output something like (hereafter noted as "Expected ouput"):

Loaded plugins: fastestmirror
...
Package 1:pkgconfig-0.23-9.1.el6.x86_64 already installed and latest version
Nothing to do

  1. Verify OpenSSL v1.0.1e-16 or later is installed. (Some prior versions contain the "Heartbleed" vulnerability.)

rpm -q -a | grep "openssl"

Expected output:

openssl-1.0.1e-51.el7_2.2.x86_64

  1. Directly download the Couchbase Server release package.

wget https://packages.couchbase.com/releases/5.0.1/couchbase-server-enterprise-5.0.1-centos7.x86_64.rpm

Expected output:

--2018-01-09 16:07:17--  https://packages.couchbase.com/releases/5.0.1/couchbase-server-enterprise-5.0.1-centos7.x86_64.rpm
Resolving packages.couchbase.com (packages.couchbase.com)... 54.192.145.11, 54.192.145.191, 54.192.145.180, ...
Connecting to packages.couchbase.com (packages.couchbase.com)|54.192.145.11|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 119728060 (114M) [application/x-rpm]
Saving to: ‘couchbase-server-enterprise-5.0.1-centos7.x86_64.rpm’

100%[======================================>] 119,728,060 71.8MB/s   in 1.6s

2018-01-09 16:07:19 (71.8 MB/s) - ‘couchbase-server-enterprise-5.0.1-centos7.x86_64.rpm’ saved [119728060/119728060]

  1. Tune system parameters

    1. Turn off "Transparent Huge Pages"

    2. Tune swap behavior

    3. Increase open file limit

echo 'never' > /sys/kernel/mm/transparent_hugepage/enabled
echo 'never' > /sys/kernel/mm/transparent_hugepage/defrag
echo 0 > /proc/sys/vm/swappiness
ulimit -n 70000

  1. Use rpm to install the downloaded package.

sudo rpm --install couchbase-server-enterprise-5.0.1-centos7.x86_64.rpm

Expected output:

Minimum RAM required  : 4 GB
System RAM configured : 3.45 GB

Minimum number of processors required : 4 cores
Number of processors on the system    : 4 cores


You have successfully installed Couchbase Server.
Please browse to http://localhost.localdomain:8091/ to configure your server.
Please refer to http://couchbase.com for additional resources.

Please note that you have to update your firewall configuration to
allow connections to the following ports:
4369, 8091 to 8094, 9100 to 9105, 9998, 9999, 11207, 11209 to 11211,
11214, 11215, 18091 to 18093, and from 21100 to 21299.

By using this software you agree to the End User License Agreement.
See /opt/couchbase/LICENSE.txt.

[N.B. Note the list of ports above Couchbase Server needs to operate. Please be sure to check your firewall settings if you have any problems connecting.]

  1. Reload systemctl configuration

systemctl daemon-reexec

  1. Start Couchbase Server

service couchbase-server start

Expected output:

Redirecting to /bin/systemctl start  couchbase-server.service

At this point Couchbase Server should be running. If this is a new installation, the next step will be to configure server parameters and create a new bucket. See Lab Exercise 1.2 for these steps.

If you have already configured one server and wish to add another to a cluster, skip to Section 2.

Lab Exercise 1.2 - Configure a Single Node

In this exercise, we will configure a newly-installed node of Couchbase Server.

  1. Open a browser and navigate to <ip address>:8091, where <ip address> is the IP address of the host machine. You should see the first page of the new configuration screens, as shown here.

New Installation Start Page

  1. Click on "Setup New Cluster"

  2. Enter a cluster name

  3. Enter and confirm a password for the Administrator

  4. Click "Next: Accept Terms"

Setup New Cluster

  1. Read the Couchbase Server Terms and Conditions

  2. Click the check box next to "I accept the terms & conditions"

  3. Click "Configure Disk, Memory, Services"

Terms and Conditions

  1. Enter the IP address of the host of the new installation

  2. Click "Save & Finish"

The Couchbase Server Console automatically attempts to provide a reasonable set of default values for the other options. You can, of course, experiment with other values.

IP address

The Couchbase Server Console will now show you the main dashboard screen, seen here.

NewDashboard

Lab Exercise 1.3 - Create a New Bucket and Add a New documentation

In this exercise, we will create a new Couchbase Server Bucket, and add a new document using the Console. Buckets are a high level organizational structure in Couchbase. You will always need at least one.

  1. On the left side of your console, click on the "Buckets" link

  2. Click on "Add Bucket" in the upper right corner

  3. In the modal dialog that appears, enter a name for the bucket

    1. You can choose most any name you like, with some restrictions

  4. Click "Add Bucket" in the dialog

The console will show you some information about the bucket, and mark it orange while the bucket is brought on line.

Creating a new bucket

  1. To the right in the bucket information row, click on "Documents"

  2. Click on "Add Document" in the upper right corner

  3. In the modal dialog, enter a document id

    1. Document IDs can be almost anything

    2. You may want to remember the ID you enter for easy access later

  4. Click "Save Document"

The console will take you to a page where you can edit your newly created documenet. You can change the document by entering any valid JSON.

  1. After the first brace, add some new data in JSON format

    1. For example, you can type the following: "add": [ "valid", "json" ],

    2. Note the editor dynamically indicates whether the JSON is valid

  2. Once you’re satisfied, click "Save"

    1. Notice the generation number of the revision id increases (shown to the right).

Creating a new document manually

You now have a document you can retrieve using direct key/value lookup (a "get" with the client).

Lab Exercise 1.4 - Create and Authorize a New User

In this exercise, we will create a user account and give access to the bucket. Client access now requires user authentication and authorization to function. Use Roll-Based Access Control to tune access rights.

  1. On the left side of your console, click on the "Security" link

  2. Click on "Add User" in the upper right corner

Creating a new bucket

This concludes the first series of exercises. At this point, you have a fully deployed, single-node instance of Couchbase. You can perform standard CRUD (create, read, update, and delete) operations using key/value lookup.

Section 2 - Creating a Multi-Node, Multi-Region Cluster

In this series of exercises, you will create two multi-node clusters, and set up data replication between them. The demonstrationsin this section use a total of six machines. To follow along, you will want to have at least two machines, either virtual or real.

Lab Exercise 2.1 - Add a Second Node to Create a Multi-Node Cluster

In this exercise, we will add a second node in combination with the first one created in Section 1. We will add the node through the administrative console on the first node. You can also join nodes to a cluster from the setup interface presented after installation.

Note the screen show adding a cluster to one with two existing nodes. The procedure is identical, independent of the number of nodes already in the cluster.

Fully adding a node is a two step process. First, add the node to the servers in the cluster.

  1. Bring up the adminstration console for the first node you created.

  2. On the left side of your console, click on the "Servers" link.

  3. In the modal dialog, enter the IP address an isolated Couchbase node.

  4. Click "Add Server".

Adding a node to a cluster

After a few seconds, the new node will be configured and ready for step 2. To activate the node, click "Rebalance" in the upper right corner of the console.

Rebalance a cluster after adding a node

This cluster has documents in it already, so the rebalance takes a little time.

Lab Exercise 2.2 - XDCR: Create a Remote Cluster Reference

In this exercise, we will create a Remote Cluster Reference. This is required to add a Cross-Data Center Replication (XDCR).

First, create a second cluster with a different cluster name following the same steps used to create the first cluster.

  1. Bring up the adminstration console for the first cluster.

  2. On the left side of your console, click on the "XDCR" link.

  3. Click on "Add Remote Cluster" on the right side of the console.

  4. In the modal dialog, enter the cluster name of the second cluster.

    1. Enter the IP address of one of the nodes of the second cluster.

    2. Enter the adminstrative account details of the second cluster.

  5. Click "Save".

Create a new cluster reference

Lab Exercise 2.3 - XDCR: Replicate a Bucket to a Remote Cluster

In this exercise, we will set up replication between two clusters. Replications are uni-directional, bucket-to-bucket, which allows you to create complex topologies.

  1. Click on "Add Replication", on the right side of the console.

  2. In the modal dialog, select the local bucket to replicate.

    1. Choose a remote cluster reference.

    2. Enter the name of the remote bucket.

  3. Click "Save".

Replicate a bucket

For bi-directional replication between two clusters, follow the setps above on the second cluster, referring back to the first cluster.

Summary

This concludes the exercises for installing and configuring a pair of clusters with redundancy between them.

In this same repository, you will find the source code for a simple Java application that uses the Couchbase Multi-Cluster Aware Java client. This client is currently under development, and is available as an Enterprise feature. Since the code for the client is not publically available, you will need to obtain a copy separately in order to build the project. Please contact a Couchbase Sales Representative for more information.