In this blog, we will explore how to run Couchbase and Couchbase Sync Gateway using Vagrant.  Before beginning, you will need to have VirtualBox and Vagrant installed locally on your machine.  Download those two software first before proceeding as you will need them to install Couchbase.  At the time of writing, I am running:

  • Vagrant:  Version 1.7.4
  • VirtualBox:  Version 5.0.10

Running Couchbase VM:

Create a directionary to work from and then from within the folder, bring in the Couchbase software distribution that is defined in a ‘Vagrantfile’ configuration file and also an associated ‘.box’ file.  You will need both these files in the directory before continuing and can find those files located in the direct ZIP download.  The next step is to set up Sync Gateway and we will do that by executing:

Disregard any warnings or connection timeouts as this process takes some time to setup.  To see the list of VM instances that are running or if ever you wish to restart/poweroff a VM, then you can execute the command:

For the example here, the name and UUID of the VirtualBox Vagrant VM that is running Sync Gateway is, ‘test_Sync_Gateway-1’ and ‘83305d4f-5fa8-4523-8037-48142b9d7ebf’ respectively which I got from running the previous command.  You should see a similar output as above before continuing.

Optionally, if you would like to shut off the VM and restart again from the beginning of the tutorial then run the command below and reference the VM UUID of interest.

Now if you check for the list of running machines, you should see none that are outputted like below.

Connect to VM:

With the ‘test_Sync_Gateway-1_…’ running, we can take a look at the status of our VM and what is running by executing:

Now we are ready to log into our machine and look at starting Sync Gateway. To do that, first we ‘SSH’ into our instance by running:

Let us take a look at the content we have in our VM.

The folder ‘finished’ contains completed code files that we will reference. Taking a look also on what is available, let us execute:

We can start our Sync Gateway by calling the script ‘’ and passing in the JSON parameter that defines our Sync Gateway configurations.

Couchbase Admin UI:

Now that you have Sync Gateway started, you are able to log into the Couchbase Admin UI.  This is located at:

  • Username:  Administrator
  • Password:   password

Open a browser and type in the URL end point and the above credentials to log in.  You would need to be connected to the VM and also have started Sync Gateway at this point to be able to login.

Click on ‘Data Buckets’ section to see that the ‘todos’ bucket details from within the Couchbase portal.  The current configurations have been set up to target the sample ToDoLite mobile application (Android | iOS) that is running Couchbase Lite.

Of course there are many other ways to set up Couchbase Sync Gateway and Couchbase Server.  You can opt for running both software from your own machine using the binaries downloaded from Couchbase or you can use the Couchbase AMI on AWS and then connect the Couchbase Sync Gateway accordingly.  Either way, you are able to quickly have a scalable solution up and running that supports a full offline mobile user experience across various platforms.  In the next blog, we explore how to do that!


Posted by William Hoang, Mobile Developer Advocate, Couchbase

William was a Developer Advocate on the Mobile Engineering/Developer Experience team at Couchbase. His love for coffee and code has transcended him into the world of mobile while appreciating the offline in-person experiences. Prior, William worked on the Developer Relations team over at Twitter, BlackBerry, and Microsoft while also having been a Software Embedded GPS engineer at Research In Motion. William graduated from McGill University in Electrical Software Engineering

Leave a reply