Help me understand the scalability plan


I’ve never worked with a server cluster before, so please help me understand how my project should play out.

I’m building a mobile trivia-type game. Coding it in Unity. The Couchbase syncing feature is a huge draw for me because the game IS essentially the database… so i want the ability for the game to be played offline, but i also want new questions to be added to the game whenever the mobile device is online.

For a week I’ve been researching this and you guys are the best fit. (My #2 and #3 picks were Firebase and Parse… however, Firebase doesn’t easily work with Unity, and Parse doesn’t easily store data offline.) So how do i go about getting started? My plan is to use a cloud platform like Google compute or aws. Do you recommend one over the other? (Does one load-balance better than the other?) Then can I start with a single instance/EC2, (like one of the “free tier” instances) and put the Server + Cluster Manager + Gateway all on that instance? Will it work? If not, what’s the minimum number of nodes to get started?

Then how do I scale up? When i get node #2, does the Gateway move to that one? How about #3? Another gateway or a second Server? And which node(s) are exposed to the Internet?

Kind regards,

Sync Gateway initial shadow scalability concerns

I’m not an expert on deployment or scaling, but I can answer the basics, and ask one of the server guys to take over.

We have various server images you can deploy on AWS/Heroku/Google to get started. IIRC they come with a single Couchbase Server node and a Sync Gateway, on the same VM. That should get you going up to a couple thousand concurrent users, depending on how active they are.

As you scale up you’ll want to separate those to their own VMs, and then add extra database or gateway nodes depending on where the load is.

You want to expose the Gateway instances to the public, but not the database nodes. Ideally you set up a load balancer to route incoming HTTP requests between the Gateway nodes — it can just route at random, it doesn’t need to keep all of a user’s requests on the same instance or anything.


@dbergan here’s a great presentation that @traun gave last week that covers these topics: Best Practices for Scaling and Deploying Couchbase Mobile in the Cloud.


If you deploy using Kubernetes, then Google compute engine is probably the easiest one to get started on, since they support Kubernetes out of the box. We’ve recently gotten Couchbase running on Kubernetes, see the couchbase/kubernetes github repo and this talk from Connect.

The value add of using Couchbase on Kubernetes is that it makes the mechanics of scaling up and down very easy. It also makes it easy to throw other components into your cluster and be able to manage them in a consistent way.

As far as whether Kubernetes is “recommended” – it’s still pre-1.0 and fairly bleeding edge, so if that’s beyond your risk level, you might want to look at some more conservative approaches like running the components directly on the virtual machines.

For that, we do have some Ansible based automation that you might want to check out, in the perfcluster-aws repo as well as in the ansible-couchbase-server repo.

You mentioned GCE and AWS, but another provider to look at is Joyent Triton, which is a “Docker container” cloud. Hosts are abstracted away, so you just deploy containers. Also since there’s no hardware virtualization, you should be able to achieve bare metal performance. See this wiki page and this talk for more info.

Yes, a single instance will work fine. The processes will be competing for resources, but if you start with a small load, it won’t be an issue.

You only want to expose the Sync Gateway node to the internet. If you have multiple Sync Gateway nodes, you’ll want to put it behind a load balancer. The link that @zgramana posted below has some more info on load balancers, as well as these docs

As far as scaling out, a “typical” cluster might be something like:

  • 3 dedicated AWS/GCE instances (virtual machines), each running Couchbase Server
  • 3 dedicated AWS/GCE instances, each running Sync Gateway
  • 1 dedicated AWS/GCE instance running Nginx

As your load increases you should be able to scale the Sync Gateway instances horizontally.

PS: we also have a Gitter chat room


Thanks a ton! These are great… really appreciate it!


Hi Traun,

I’m attracted to the kubernetes solution. But after looking at the github readme I have a couple questions…

  1. What’s this etcd stuff? This section totally lost me:

“The etcd service is used by “sidekicks” that run in the Couchbase Server pod to bootstrap the cluster. Likewise, it is only accessible within the cluster.”

(Sorry, I’m pretty green when it comes to understanding Linux OS and command shell prompts… so i don’t know what etcd, sidekicks, or bootstraps are.)

  1. Is there a way to install kubectl on Windows?

I was able to follow the rest of the article, so hopefully I can get this spinning this weekend.

Thanks again for all the help.

Kind regards,


would a round robin config for: -> NGINX1 (VM1) / NGINX2 (VM2) / NGINX3 (VM3)

and then:


and then


work (without problems) / work better than


i’m also wondering how redundant NGINX is in the earlier setup above…


I wouldn’t go that direction unless you have clear evidence that you are seeing bottlenecks with a single NGINX box.

Also looping back to Kubernetes, keep an eye out for announcements of native Kubernetes support for Couchbase sometime in 2018. This is currently in the works by a dedicated team within Couchbase.

Sneak preview here: