This folder contains a script for configuring and initializing Couchbase on an AWS server.
This script has been tested on the following operating systems:
Ubuntu 16.04
Amazon Linux 2
There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.
Quick start
This script assumes you installed it, plus all of its dependencies (including Couchbase itself), using the
install-couchbase-server module.
The default install path is /opt/couchbase/bin, so to configure and start Couchbase, you run:
Figure out a rally point for your Couchbase cluster. This is a "leader" node that will be responsible for
initializing the cluster and/or replication. See Picking a rally point for more info.
Configure ports.
Start Couchbase on the local node.
On the rally point, initialize the cluster, including configuring which services to run, credentials, and memory
settings.
On all other nodes, join the existing cluster.
We recommend using the run-couchbase-server command as part of User
Data, so that it executes
when the EC2 Instance is first booting.
Run run-couchbase-server --help to see all available arguments.
Usage: run-couchbase-server [options]
This script can be used to configure and initialize a Couchbase Server. This script has been tested with Ubuntu 16.04 and Amazon Linux 2.
Required arguments:
--cluster-username The username for the Couchbase cluster.
--cluster-password The password for the Couchbase cluster.
Important optional arguments:
--node-services Comma-separated list of Couchbase services torun on this node. Default: data,index,query,fts.
--cluster-services Comma-separated list of Couchbase services you plan torunin this cluster. Only used when initializing a new cluster. Default: data,index,query,fts.
--cluster-name The name of the Couchbase cluster. Must be the name of an Auto Scaling Group (ASG). Default: use the name of the ASG this node is in.
--hostname The hostname to use for this node. Default: look up the node's private hostname in EC2 metadata.
--use-public-hostname If this flag is set, use the node's public hostname from EC2 metadata.
--rally-point-hostname The hostname of the rally point server that initialized the cluster. Ifnot set, automatically pick a rally point server in the ASG.
--data-dir The path to store data files create by the Couchbase data service. Default: /opt/couchbase/var/lib/couchbase/data.
--index-dir The path to store files create by the Couchbase index service. Default: /opt/couchbase/var/lib/couchbase/data.
Optional port settings:
--rest-port The port to use for the Couchbase Web Console and REST/HTTP API. Default: 8091.
--capi-port The port to use for Views and XDCR access. Default: 8092.
--query-port The port to use for the Query service REST/HTTP traffic. Default: 8093.
--fts-port The port to use for the Search service REST/HTTP traffic. Default: 8094.
--memcached-port The port to use for the Data service. Default: 11210.
--xdcr-port The port to use for the XDCR REST traffic. Default: 9998.
Other optional arguments:
--index-storage-setting The index storage mode for the index service. Must be one of: default, memopt. Default: default.
--manage-memory-manually If this flag is set, you can set memory settings manually via the --data-ramsize, --fts-ramsize, and --index-ramsize arguments.
--data-ramsize The data service memory quota in MB. Only used when initializing a new cluster andif --manage-memory-manually is set.
--index-ramsize The index service memory quota in MB. Only used when initializing a new cluster andif --manage-memory-manually is set.
--fts-ramsize The full-text service memory quota in MB. Only used when initializing a new cluster andif --manage-memory-manually is set.
--wait-for-all-nodes If this flag is set, this script will wait until all servers in the Couchbase Cluster are added and running.
--help Show this help text and exit.
Example:
run-couchbase-server --cluster-username admin --cluser-password password
Picking a rally point
The Couchbase cluster needs a "rally point", which is a single server that is responsible for:
Initializing the cluster.
Kicking off cross-data-center replication (if you're using it).
We need a way to unambiguously and reliably select exactly one rally point. If there's more than one node, you may end
up with multiple separate clusters instead of just one!
The run-couchbase-server script can automatically pick a rally point automatically by:
Looking up all the servers in the Auto Scaling Group specified via the --cluster-name parameter. If the parameter
is not specified, the name of the Auto Scaling Group in which run-couchbase-server is running is used.
Pick the node with the oldest Launch Time as the rally point. If multiple nodes have identical launch times, use the
one with the earliest Instance ID, alphabetically.
If you wish to specify a rally point manually instead of relying on this automatic process, use the
--rally-point-hostname parameter.
Running multiple Auto Scaling Groups
The recommended deployment pattern for production is to run each Couchbase service (data, index, fts, query) and Sync
Gateway in separate Auto Scaling Groups (ASGs). To ensure that all of these ASGs form a single Couchbase cluster, you
should:
Pick one ASG as the one that will contain the rally point (see Picking a rally point).
Typically, this will be the ASG with the data nodes.
When executing the run-couchbase-server script, set the --cluster-name parameter on all nodes to the name of
the ASG you picked in step (1).
When executing run-sync-gateway script, set ASG_NAME in the --auto-fill-asg KEY=ASG_NAME parameter to the name
of the ASG you picked in step (1).
Passing credentials securely
The run-couchbase-server requires that you pass in your cluster username and password. You should make sure to never
store these credentials in plaintext! You should use a secrets management tool to store the credentials in an encrypted
format and only decrypt them, in memory, just before calling run-couchbase-server. Here are some tools to consider:
Moreover, if you're ever calling run-couchbase-server interactively (i.e., you're manually running CLI commands
rather than executing a script), be careful of passing credentials directly on the command line, or they will be
stored, in plaintext, in Bash
history!
You can either use a CLI tool to set the credentials as environment variables or you can temporarily disable Bash
history.
Required permissions
The run-couchbase-server script assumes it is running on an EC2 Instance with an IAM
Role that has the following permissions:
By default, the run-couchbase-server script uses a simple formula to automatically determine memory quotas for the
data, index, and search services:
The total memory available to couchbase is 65% of the RAM on the current node.
If you are only running a single service on this node, give that service 100% of the available memory.
If you are running all three services, give data 50%, index 25%, and search 25%.
If you are running data and one other service, give data 65% and the other service 35%.
If you are running index and search, give each 50%.
Ensure no service is allocated less than 256MB.
You can override this simple calculation by setting the --manage-memory-manually flag and specifying the amount of
memory, in MB, for each service you plan on running using the --data-ramsize, --index-ramsize, and --fts-ramsize
parameters. Example:
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"193cb67012263437903101c15897eb82471f70fc"},{"name":"publish-amis.sh","path":".circleci/publish-amis.sh","sha":"abb6cf0e36e53f65074d47170f147d06036f5797"}]},{"name":".gitignore","path":".gitignore","sha":"85435101db88fb540a38f4b6dfa03ffd79d97633"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"1142c08a1fb176570e5470375e110838234ebfa4"},{"name":".pre-commit-hooks.yaml","path":".pre-commit-hooks.yaml","sha":"92462242c5c4a3aa0f5d5f5b19a81811c71e4b49"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"28333bea0519ace338740140eff651c08cbf27d7"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"de3aa54eede67b6eddf1776e08f8441973f57fc1"},{"name":"LICENSE","path":"LICENSE","sha":"7a4a3ea2424c09fbe48d455aed1eaa94d9124835"},{"name":"NOTICE","path":"NOTICE","sha":"77030eb8f10190ffd42c28bb41922f8c91b089a1"},{"name":"README.md","path":"README.md","sha":"ddbfff5345200723a3881695f9e8fd3cd6d4bb77"},{"name":"_docs","children":[{"name":"couchbase-multi-cluster-architecture.png","path":"_docs/couchbase-multi-cluster-architecture.png","sha":"60ec0e7cca94e2400662b7ed8565833b84f142be"},{"name":"couchbase-multi-datacenter-replication-architecture.png","path":"_docs/couchbase-multi-datacenter-replication-architecture.png","sha":"d19384e42f436e9a96ae112853e679208d8cc513"},{"name":"couchbase-multi-datacenter-replication-architecture.psd","path":"_docs/couchbase-multi-datacenter-replication-architecture.psd","sha":"9750878217d877c6fed0d70c57d4e4f1ed732a4a"},{"name":"couchbase-single-cluster-architecture.png","path":"_docs/couchbase-single-cluster-architecture.png","sha":"448144c58bddc5bf46c096289344d66733bc7592"}]},{"name":"examples","children":[{"name":"couchbase-ami","children":[{"name":"README.md","path":"examples/couchbase-ami/README.md","sha":"db19908786e1f925f14a63e9f74e12be68ecea41"},{"name":"couchbase.json","path":"examples/couchbase-ami/couchbase.json","sha":"2071002cbd823dbdca82d0fa2df41d5edabd993d"},{"name":"sync_gateway.json","path":"examples/couchbase-ami/sync_gateway.json","sha":"067df37d31d51feae93105d11ed8d1539f7c6e3a"}]},{"name":"couchbase-cluster-mds","children":[{"name":"README.md","path":"examples/couchbase-cluster-mds/README.md","sha":"ad316fdc85a5687e6310614d1d48f6fa9dcc33bc"},{"name":"local-test","children":[{"name":".env","path":"examples/couchbase-cluster-mds/local-test/.env","sha":"fb429afef6ea74aa33abe5e4319b3538a2bd7263"},{"name":"docker-compose.yml","path":"examples/couchbase-cluster-mds/local-test/docker-compose.yml","sha":"791983d4ac39cc4ff6f7f613e1d78976287f6dbf"}]},{"name":"main.tf","path":"examples/couchbase-cluster-mds/main.tf","sha":"cd89e4c4b2139134ceefcc709a00543e843adf54"},{"name":"outputs.tf","path":"examples/couchbase-cluster-mds/outputs.tf","sha":"4a60475339777bdbf95b6045d7d2e956c2dbe927"},{"name":"user-data","children":[{"name":"user-data-couchbase-data-nodes.sh","path":"examples/couchbase-cluster-mds/user-data/user-data-couchbase-data-nodes.sh","sha":"feb4ae958397c19ded82e21fb60578fbb1ac19e3"},{"name":"user-data-couchbase-index-query-search-nodes.sh","path":"examples/couchbase-cluster-mds/user-data/user-data-couchbase-index-query-search-nodes.sh","sha":"c13d780c95601b1bfa157d65329312866a18f3ff"},{"name":"user-data-sync-gateway.sh","path":"examples/couchbase-cluster-mds/user-data/user-data-sync-gateway.sh","sha":"99aa5e77cfff2774bd0020d51ea6ba77a49a3674"}]},{"name":"variables.tf","path":"examples/couchbase-cluster-mds/variables.tf","sha":"779b652d4ae2bee64e852131b9ca85f39f0bdfd8"}]},{"name":"couchbase-cluster-simple-dns-tls","children":[{"name":"README.md","path":"examples/couchbase-cluster-simple-dns-tls/README.md","sha":"d2e537222684a472713c29292f4160f811b3ed62"},{"name":"local-test","children":[{"name":".env","path":"examples/couchbase-cluster-simple-dns-tls/local-test/.env","sha":"fb429afef6ea74aa33abe5e4319b3538a2bd7263"},{"name":"docker-compose.yml","path":"examples/couchbase-cluster-simple-dns-tls/local-test/docker-compose.yml","sha":"e8980454ea06f365ee92df93aaf6b007c20437cf"}]},{"name":"main.tf","path":"examples/couchbase-cluster-simple-dns-tls/main.tf","sha":"21623b967fa4e0f2224d89cec5ea8d4a9a67d028"},{"name":"outputs.tf","path":"examples/couchbase-cluster-simple-dns-tls/outputs.tf","sha":"bf8c18b332125a2e0e68e210b26fa48dd6594039"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/couchbase-cluster-simple-dns-tls/user-data/user-data.sh","sha":"bf62d443d7e8226ee7630d5807b3e4be533151f8"}]},{"name":"variables.tf","path":"examples/couchbase-cluster-simple-dns-tls/variables.tf","sha":"c4b4418dc839693bd8dbde269a82ac31ef03ce7c"}]},{"name":"couchbase-cluster-simple","children":[{"name":"README.md","path":"examples/couchbase-cluster-simple/README.md","sha":"e4126f146380b68bca8e2075b3579c32d564a2f5"},{"name":"local-test","children":[{"name":".env","path":"examples/couchbase-cluster-simple/local-test/.env","sha":"fb429afef6ea74aa33abe5e4319b3538a2bd7263"},{"name":"docker-compose.yml","path":"examples/couchbase-cluster-simple/local-test/docker-compose.yml","sha":"e8980454ea06f365ee92df93aaf6b007c20437cf"}]},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/couchbase-cluster-simple/user-data/user-data.sh","sha":"f5107d31dd228a3268a894f86978fa30abc29d20"}]}]},{"name":"couchbase-multi-datacenter-replication","children":[{"name":"README.md","path":"examples/couchbase-multi-datacenter-replication/README.md","sha":"e7b299a03d14f1ff713fc57363d6c9e250bbc1ed"},{"name":"local-test","children":[{"name":".env","path":"examples/couchbase-multi-datacenter-replication/local-test/.env","sha":"6112e2bcb38259397b81257ebbf422ebaccec068"},{"name":"docker-compose.yml","path":"examples/couchbase-multi-datacenter-replication/local-test/docker-compose.yml","sha":"12db84e3008f3498f58fe6bb64afcf4d69448410"}]},{"name":"main.tf","path":"examples/couchbase-multi-datacenter-replication/main.tf","sha":"5773fad2e489d3cefd5a2e03de92c83a886c1263"},{"name":"outputs.tf","path":"examples/couchbase-multi-datacenter-replication/outputs.tf","sha":"b176beecefad8213f0c8d953cb1451deb827dba8"},{"name":"user-data","children":[{"name":"user-data-primary.sh","path":"examples/couchbase-multi-datacenter-replication/user-data/user-data-primary.sh","sha":"71a34464aaee5f324190f9fa60f620769a9923a8"},{"name":"user-data-replica.sh","path":"examples/couchbase-multi-datacenter-replication/user-data/user-data-replica.sh","sha":"aa410fd045f04a9788a7b09fa5fb2c03970a5f0e"}]},{"name":"variables.tf","path":"examples/couchbase-multi-datacenter-replication/variables.tf","sha":"99c18d0b5dcda11b3999a3cae808f80944be9255"}]},{"name":"local-mocks","children":[{"name":"README.md","path":"examples/local-mocks/README.md","sha":"4c6d80b3998e1027f5c2a4c71715772b81830b31"},{"name":"aws.sh","path":"examples/local-mocks/aws.sh","sha":"20408cfe23eb7a3cf2451fbb7d8214a0b746b1cc"},{"name":"entrypoint.sh","path":"examples/local-mocks/entrypoint.sh","sha":"51c897ba4b159e58381eb23b760c84696dc9b681"},{"name":"mount-volume.sh","path":"examples/local-mocks/mount-volume.sh","sha":"c9fa0b283e7ce1a0b1652dc4565bfe2740dcc820"}]}]},{"name":"main.tf","path":"main.tf","sha":"1868c0ad8ffa0ce7ebbe695d733820e3ea188426"},{"name":"modules","children":[{"name":"couchbase-cluster","children":[{"name":"README.md","path":"modules/couchbase-cluster/README.md","sha":"bb1edabb679a103375a61ed16fa0ad6f63991a50"},{"name":"main.tf","path":"modules/couchbase-cluster/main.tf","sha":"ed88c06cd25e6926b9b228a1eb66a35b52880070"},{"name":"outputs.tf","path":"modules/couchbase-cluster/outputs.tf","sha":"43f4b8d33b580deface276e3f49680e26daf7b7c"},{"name":"variables.tf","path":"modules/couchbase-cluster/variables.tf","sha":"188c2383e0211961663d26d98216ac3dd0a76418"}]},{"name":"couchbase-commons","children":[{"name":"README.md","path":"modules/couchbase-commons/README.md","sha":"f1367ace90480981e5dceba2c7cb84f6878a1fb8"},{"name":"couchbase-common.sh","path":"modules/couchbase-commons/couchbase-common.sh","sha":"6ef25a60dabe4182d0805d115a6fed1cba5422a0"},{"name":"couchbase-rally-point","path":"modules/couchbase-commons/couchbase-rally-point","sha":"103bc2dbc4b2a7d51b56f08eb186ce2f00b323c7"},{"name":"mount-volume.sh","path":"modules/couchbase-commons/mount-volume.sh","sha":"3767b9a3ea78e4fa1f48f29866dcef430a5fa9fe"}]},{"name":"couchbase-iam-policies","children":[{"name":"README.md","path":"modules/couchbase-iam-policies/README.md","sha":"922154296ebbb41e9343b0ead8fb469007944048"},{"name":"main.tf","path":"modules/couchbase-iam-policies/main.tf","sha":"e29f3ca8e36f743680465589e7a154d986a28367"},{"name":"variables.tf","path":"modules/couchbase-iam-policies/variables.tf","sha":"26ac224bac34cf635bff250be92515b7b6f97070"}]},{"name":"couchbase-server-security-group-rules","children":[{"name":"README.md","path":"modules/couchbase-server-security-group-rules/README.md","sha":"208e46d7c9647c61941dd77b212009fab3d16fd5"},{"name":"main.tf","path":"modules/couchbase-server-security-group-rules/main.tf","sha":"5d0f320b8f97d6f9855e748495c8e27315d47522"},{"name":"outputs.tf","path":"modules/couchbase-server-security-group-rules/outputs.tf","sha":"4c5c8af8a2fb065200fdc7090a9c1b5cd226d5d6"},{"name":"variables.tf","path":"modules/couchbase-server-security-group-rules/variables.tf","sha":"1f00f38fc9e89210f0ca8bc2189d6615a9e4481b"}]},{"name":"install-couchbase-server","children":[{"name":"README.md","path":"modules/install-couchbase-server/README.md","sha":"c61cfa9d91a6fdaf8b269dbe9e00018addb74786"},{"name":"disable-thp","path":"modules/install-couchbase-server/disable-thp","sha":"2ead9b6e580a16712375f207ba4261884157f88e"},{"name":"install-couchbase-server","path":"modules/install-couchbase-server/install-couchbase-server","sha":"ebee490745cf82f243b3521a6f723a50c76ac57d"}]},{"name":"install-sync-gateway","children":[{"name":"README.md","path":"modules/install-sync-gateway/README.md","sha":"abf0948beecb4ab06a9d55c402d8c1b444d95c6d"},{"name":"install-sync-gateway","path":"modules/install-sync-gateway/install-sync-gateway","sha":"4b1d60c9e73bc5d10801bb80949708efe8f0b311"}]},{"name":"load-balancer-target-group","children":[{"name":"README.md","path":"modules/load-balancer-target-group/README.md","sha":"b71f21e4aa7c506b9a4df23919e2e844609c6b73"},{"name":"main.tf","path":"modules/load-balancer-target-group/main.tf","sha":"e466de27ac669e03b3e6074a3e5d3c7ca5beb2e8"},{"name":"outputs.tf","path":"modules/load-balancer-target-group/outputs.tf","sha":"c66bcfb9097a75d942502aa134cdc1809e108e28"},{"name":"variables.tf","path":"modules/load-balancer-target-group/variables.tf","sha":"d0bbba3368e012a21a9254b54606dab54f44a20f"}]},{"name":"load-balancer","children":[{"name":"README.md","path":"modules/load-balancer/README.md","sha":"c3e457f41ef1b3797e96bd395931b4b86d8763f7"},{"name":"main.tf","path":"modules/load-balancer/main.tf","sha":"b2125b3f14f65a38814e1babddca7ca321701064"},{"name":"outputs.tf","path":"modules/load-balancer/outputs.tf","sha":"74124a4d0972376f7756ba927604637536b4a7b6"},{"name":"variables.tf","path":"modules/load-balancer/variables.tf","sha":"990d99f7ef2bc15d0656b66c8640e01393f9d10b"}]},{"name":"run-couchbase-server","children":[{"name":"README.md","path":"modules/run-couchbase-server/README.md","sha":"e76309c1cec9658a928bc868a21efac02312e72f","toggled":true},{"name":"run-couchbase-server","path":"modules/run-couchbase-server/run-couchbase-server","sha":"625f642186f6d10e1e2e7870da264a462bc18554"}],"toggled":true},{"name":"run-replication","children":[{"name":"README.md","path":"modules/run-replication/README.md","sha":"70b7aa50e06d1c390b2f7921e8293c4e45de4fae"},{"name":"run-replication","path":"modules/run-replication/run-replication","sha":"419c2f1cca183fd2f1fd9a94a11ba587609edded"}]},{"name":"run-sync-gateway","children":[{"name":"README.md","path":"modules/run-sync-gateway/README.md","sha":"0a0d2c6391c30545d5e80fb1f34b568c6231cee4"},{"name":"run-sync-gateway","path":"modules/run-sync-gateway/run-sync-gateway","sha":"8f827839afe57bd36a4a6c35ef2a169fa6992054"}]},{"name":"sync-gateway-security-group-rules","children":[{"name":"README.md","path":"modules/sync-gateway-security-group-rules/README.md","sha":"f5e50b67844506d15a277e3578105dc3a1225c95"},{"name":"main.tf","path":"modules/sync-gateway-security-group-rules/main.tf","sha":"87028ff2de4562224ec2d20986acbe1eb4faaeee"},{"name":"outputs.tf","path":"modules/sync-gateway-security-group-rules/outputs.tf","sha":"20655ee9c7729f093241ec28e31b197e7d4fbdca"},{"name":"variables.tf","path":"modules/sync-gateway-security-group-rules/variables.tf","sha":"cf39a81712ec01fc36b9f83dd7e62226b1d08a60"}]}],"toggled":true},{"name":"outputs.tf","path":"outputs.tf","sha":"4138cc3c41b0d5ebf4ce088431332550eb503e10"},{"name":"test","children":[{"name":"Gopkg.lock","path":"test/Gopkg.lock","sha":"42577e372ee9d685a77d83537a631f1d6c18fdf5"},{"name":"Gopkg.toml","path":"test/Gopkg.toml","sha":"4925cde6b22bd6697a2f5fb81a86ba60628786a5"},{"name":"README.md","path":"test/README.md","sha":"36e97d94c441e302871e22126004113f3ffb84d1"},{"name":"couchbase_helpers.go","path":"test/couchbase_helpers.go","sha":"43bddbac0885037fcadcdcf81ccafdeeabe16a37"},{"name":"couchbase_multi_cluster_test.go","path":"test/couchbase_multi_cluster_test.go","sha":"3f4ce22c64179b7c04710e7903dc616722215131"},{"name":"couchbase_multi_datacenter_replication_test.go","path":"test/couchbase_multi_datacenter_replication_test.go","sha":"cdb6df8391670b38cb7185d97f3522eabba7cee4"},{"name":"couchbase_single_cluster_dns_tls_test.go","path":"test/couchbase_single_cluster_dns_tls_test.go","sha":"0fd10dc7be5d802ad648fec8d486f81d681ebfc0"},{"name":"couchbase_single_cluster_test.go","path":"test/couchbase_single_cluster_test.go","sha":"4defb9cda7c5b2d0077849b4869d6c72c0876456"},{"name":"docker_compose_test.go","path":"test/docker_compose_test.go","sha":"29c79d54d53f5858a9ad3713ff80d1799d63a9f3"},{"name":"terratest_helpers.go","path":"test/terratest_helpers.go","sha":"29cc6e09e083f421dbfc153990b3d3fe9cc8cf76"}]},{"name":"variables.tf","path":"variables.tf","sha":"e463cef71c94336b5f14de9f3ddc1cdf7d4edaec"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"couchbase-server-run-script\">Couchbase Server Run Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for configuring and initializing Couchbase on an <a href=\"https://aws.amazon.com/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS</a> server.\nThis script has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 16.04</li>\n<li>Amazon Linux 2</li>\n</ul>\n<p>There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.</p>\n<h2 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h2>\n<p>This script assumes you installed it, plus all of its dependencies (including Couchbase itself), using the\n<a href=\"/repos/v0.2.2/terraform-aws-couchbase/modules/install-couchbase-server\" class=\"preview__body--description--blue\">install-couchbase-server module</a>.\nThe default install path is <code>/opt/couchbase/bin</code>, so to configure and start Couchbase, you run:</p>\n<pre><span class=\"hljs-meta-keyword\">/opt/</span>couchbase<span class=\"hljs-meta-keyword\">/bin/</span>run-couchbase-server --cluster-username <span class=\"hljs-params\"><USERNAME></span> --cluser-password <span class=\"hljs-params\"><PASSWORD></span>\n</pre>\n<p>This will:</p>\n<ol>\n<li>\n<p>Figure out a rally point for your Couchbase cluster. This is a "leader" node that will be responsible for\ninitializing the cluster and/or replication. See <a href=\"#picking-a-rally-point\" class=\"preview__body--description--blue\">Picking a rally point</a> for more info.</p>\n</li>\n<li>\n<p>Configure ports.</p>\n</li>\n<li>\n<p>Start Couchbase on the local node.</p>\n</li>\n<li>\n<p>On the rally point, initialize the cluster, including configuring which services to run, credentials, and memory\nsettings.</p>\n</li>\n<li>\n<p>On all other nodes, join the existing cluster.</p>\n</li>\n</ol>\n<p>We recommend using the <code>run-couchbase-server</code> command as part of <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts\" class=\"preview__body--description--blue\" target=\"_blank\">User\nData</a>, so that it executes\nwhen the EC2 Instance is first booting.</p>\n<p>See the <a href=\"/repos/v0.2.2/terraform-aws-couchbase/examples\" class=\"preview__body--description--blue\">examples folder</a> for\nfully-working sample code.</p>\n<h2 class=\"preview__body--subtitle\" id=\"command-line-arguments\">Command line Arguments</h2>\n<p>Run <code>run-couchbase-server --help</code> to see all available arguments.</p>\n<pre><span class=\"hljs-attribute\">Usage</span>: run-couchbase-server [options]\n\n<span class=\"routeros\">This<span class=\"hljs-built_in\"> script </span>can be used <span class=\"hljs-keyword\">to</span> configure <span class=\"hljs-keyword\">and</span> initialize a Couchbase Server. This<span class=\"hljs-built_in\"> script </span>has been tested with Ubuntu 16.04 <span class=\"hljs-keyword\">and</span> Amazon Linux 2.\n\nRequired arguments:\n\n --cluster-username\t\tThe username <span class=\"hljs-keyword\">for</span> the Couchbase cluster.\n --cluster-password\t\tThe password <span class=\"hljs-keyword\">for</span> the Couchbase cluster.\n\nImportant optional arguments:\n\n --node-services\t\tComma-separated list of Couchbase services <span class=\"hljs-keyword\">to</span> <span class=\"hljs-builtin-name\">run</span> on this node. Default: data,index,query,fts.\n --cluster-services\t\tComma-separated list of Couchbase services you plan <span class=\"hljs-keyword\">to</span> <span class=\"hljs-builtin-name\">run</span> <span class=\"hljs-keyword\">in</span> this cluster. Only used when initializing a new cluster. Default: data,index,query,fts.\n --cluster-name\t\tThe name of the Couchbase cluster. Must be the name of an Auto Scaling<span class=\"hljs-built_in\"> Group </span>(ASG). Default: use the name of the ASG this node is <span class=\"hljs-keyword\">in</span>.\n --hostname\t\t\tThe hostname <span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> this node. Default: look up the node<span class=\"hljs-string\">'s private hostname in EC2 metadata.\n --use-public-hostname\t\tIf this flag is set, use the node'</span>s public hostname <span class=\"hljs-keyword\">from</span> EC2 metadata.\n --rally-point-hostname\tThe hostname of the rally point<span class=\"hljs-built_in\"> server </span>that initialized the cluster. <span class=\"hljs-keyword\">If</span> <span class=\"hljs-keyword\">not</span> set, automatically pick a rally point<span class=\"hljs-built_in\"> server </span><span class=\"hljs-keyword\">in</span> the ASG.\n --data-dir\t\t\tThe path <span class=\"hljs-keyword\">to</span> store data files create by the Couchbase data service. Default: /opt/couchbase/var/lib/couchbase/data.\n --index-dir\t\t\tThe path <span class=\"hljs-keyword\">to</span> store files create by the Couchbase index service. Default: /opt/couchbase/var/lib/couchbase/data.\n\nOptional<span class=\"hljs-built_in\"> port </span>settings:\n\n --rest-port\t\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> the Couchbase Web<span class=\"hljs-built_in\"> Console </span><span class=\"hljs-keyword\">and</span> REST/HTTP API. Default: 8091.\n --capi-port\t\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> Views <span class=\"hljs-keyword\">and</span> XDCR access. Default: 8092.\n --query-port\t\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> the Query<span class=\"hljs-built_in\"> service </span>REST/HTTP traffic. Default: 8093.\n --fts-port\t\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> the Search<span class=\"hljs-built_in\"> service </span>REST/HTTP traffic. Default: 8094.\n --memcached-port\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> the Data service. Default: 11210.\n --xdcr-port\t\t\tThe<span class=\"hljs-built_in\"> port </span><span class=\"hljs-keyword\">to</span> use <span class=\"hljs-keyword\">for</span> the XDCR REST traffic. Default: 9998.\n\nOther optional arguments:\n\n --index-storage-setting\tThe index storage mode <span class=\"hljs-keyword\">for</span> the index service. Must be one of: default, memopt. Default: default.\n --manage-memory-manually\t<span class=\"hljs-keyword\">If</span> this flag is set, you can <span class=\"hljs-builtin-name\">set</span> memory<span class=\"hljs-built_in\"> settings </span>manually via the --data-ramsize, --fts-ramsize, <span class=\"hljs-keyword\">and</span> --index-ramsize arguments.\n --data-ramsize\t\tThe data<span class=\"hljs-built_in\"> service </span>memory quota <span class=\"hljs-keyword\">in</span> MB. Only used when initializing a new cluster <span class=\"hljs-keyword\">and</span> <span class=\"hljs-keyword\">if</span> --manage-memory-manually is set.\n --index-ramsize\t\tThe index<span class=\"hljs-built_in\"> service </span>memory quota <span class=\"hljs-keyword\">in</span> MB. Only used when initializing a new cluster <span class=\"hljs-keyword\">and</span> <span class=\"hljs-keyword\">if</span> --manage-memory-manually is set.\n --fts-ramsize\t\t\tThe full-text<span class=\"hljs-built_in\"> service </span>memory quota <span class=\"hljs-keyword\">in</span> MB. Only used when initializing a new cluster <span class=\"hljs-keyword\">and</span> <span class=\"hljs-keyword\">if</span> --manage-memory-manually is set.\n --wait-for-all-nodes\t\t<span class=\"hljs-keyword\">If</span> this flag is set, this<span class=\"hljs-built_in\"> script </span>will wait until all servers <span class=\"hljs-keyword\">in</span> the Couchbase Cluster are added <span class=\"hljs-keyword\">and</span> running.\n --help\t\t\tShow this help text <span class=\"hljs-keyword\">and</span> exit.\n\nExample:\n\n run-couchbase-server --cluster-username admin --cluser-password password\n</span></pre>\n<h2 class=\"preview__body--subtitle\" id=\"picking-a-rally-point\">Picking a rally point</h2>\n<p>The Couchbase cluster needs a "rally point", which is a single server that is responsible for:</p>\n<ol>\n<li>Initializing the cluster.</li>\n<li>Kicking off cross-data-center replication (if you're using it).</li>\n</ol>\n<p>We need a way to unambiguously and reliably select exactly one rally point. If there's more than one node, you may end\nup with multiple separate clusters instead of just one!</p>\n<p>The <code>run-couchbase-server</code> script can automatically pick a rally point automatically by:</p>\n<ol>\n<li>\n<p>Looking up all the servers in the Auto Scaling Group specified via the <code>--cluster-name</code> parameter. If the parameter\nis not specified, the name of the Auto Scaling Group in which <code>run-couchbase-server</code> is running is used.</p>\n</li>\n<li>\n<p>Pick the node with the oldest Launch Time as the rally point. If multiple nodes have identical launch times, use the\none with the earliest Instance ID, alphabetically.</p>\n</li>\n</ol>\n<p>If you wish to specify a rally point manually instead of relying on this automatic process, use the\n<code>--rally-point-hostname</code> parameter.</p>\n<h2 class=\"preview__body--subtitle\" id=\"running-multiple-auto-scaling-groups\">Running multiple Auto Scaling Groups</h2>\n<p>The recommended deployment pattern for production is to run each Couchbase service (data, index, fts, query) and Sync\nGateway in separate Auto Scaling Groups (ASGs). To ensure that all of these ASGs form a single Couchbase cluster, you\nshould:</p>\n<ol>\n<li>\n<p>Pick one ASG as the one that will contain the rally point (see <a href=\"#picking-a-rally-point\" class=\"preview__body--description--blue\">Picking a rally point</a>).\nTypically, this will be the ASG with the data nodes.</p>\n</li>\n<li>\n<p>When executing the <code>run-couchbase-server</code> script, set the <code>--cluster-name</code> parameter on all nodes to the name of\nthe ASG you picked in step (1).</p>\n</li>\n<li>\n<p>When executing <code>run-sync-gateway</code> script, set <code>ASG_NAME</code> in the <code>--auto-fill-asg KEY=ASG_NAME</code> parameter to the name\nof the ASG you picked in step (1).</p>\n</li>\n</ol>\n<h2 class=\"preview__body--subtitle\" id=\"passing-credentials-securely\">Passing credentials securely</h2>\n<p>The <code>run-couchbase-server</code> requires that you pass in your cluster username and password. You should make sure to never\nstore these credentials in plaintext! You should use a secrets management tool to store the credentials in an encrypted\nformat and only decrypt them, in memory, just before calling <code>run-couchbase-server</code>. Here are some tools to consider:</p>\n<ul>\n<li><a href=\"https://www.vaultproject.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Vault</a></li>\n<li><a href=\"https://square.github.io/keywhiz/\" class=\"preview__body--description--blue\" target=\"_blank\">Keywhiz</a></li>\n<li><a href=\"https://aws.amazon.com/kms/\" class=\"preview__body--description--blue\" target=\"_blank\">KMS</a></li>\n</ul>\n<p>Moreover, if you're ever calling <code>run-couchbase-server</code> interactively (i.e., you're manually running CLI commands\nrather than executing a script), be careful of passing credentials directly on the command line, or they will be\nstored, in plaintext, <a href=\"https://www.digitalocean.com/community/tutorials/how-to-use-bash-history-commands-and-expansions-on-a-linux-vps\" class=\"preview__body--description--blue\" target=\"_blank\">in Bash\nhistory</a>!\nYou can either use a CLI tool to set the credentials as environment variables or you can <a href=\"https://linuxconfig.org/how-to-disable-bash-shell-commands-history-on-linux\" class=\"preview__body--description--blue\" target=\"_blank\">temporarily disable Bash\nhistory</a>.</p>\n<h2 class=\"preview__body--subtitle\" id=\"required-permissions\">Required permissions</h2>\n<p>The <code>run-couchbase-server</code> script assumes it is running on an EC2 Instance with an <a href=\"http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html\" class=\"preview__body--description--blue\" target=\"_blank\">IAM\nRole</a> that has the following permissions:</p>\n<ul>\n<li><code>ec2:DescribeInstances</code></li>\n<li><code>ec2:DescribeTags</code></li>\n<li><code>autoscaling:DescribeAutoScalingGroups</code></li>\n</ul>\n<p>These permissions are automatically added by the <a href=\"/repos/v0.2.2/terraform-aws-couchbase/modules/couchbase-cluster\" class=\"preview__body--description--blue\">couchbase-cluster\nmodule</a>.</p>\n<h2 class=\"preview__body--subtitle\" id=\"memory-settings\">Memory settings</h2>\n<p>By default, the <code>run-couchbase-server</code> script uses a simple formula to automatically determine memory quotas for the\ndata, index, and search services:</p>\n<ul>\n<li>The total memory available to couchbase is 65% of the RAM on the current node.</li>\n<li>If you are only running a single service on this node, give that service 100% of the available memory.</li>\n<li>If you are running all three services, give data 50%, index 25%, and search 25%.</li>\n<li>If you are running data and one other service, give data 65% and the other service 35%.</li>\n<li>If you are running index and search, give each 50%.</li>\n<li>Ensure no service is allocated less than 256MB.</li>\n</ul>\n<p>You can override this simple calculation by setting the <code>--manage-memory-manually</code> flag and specifying the amount of\nmemory, in MB, for each service you plan on running using the <code>--data-ramsize</code>, <code>--index-ramsize</code>, and <code>--fts-ramsize</code>\nparameters. Example:</p>\n<pre><span class=\"hljs-built_in\">run</span>-couchbase-server \\ \n <span class=\"hljs-comment\">--cluster-username admin \\</span>\n <span class=\"hljs-comment\">--cluster-password password \\</span>\n <span class=\"hljs-comment\">--manage-memory-manually \\</span>\n <span class=\"hljs-comment\">--data-ramsize 2048 \\</span>\n <span class=\"hljs-comment\">--index-ramsize 1024 \\</span>\n <span class=\"hljs-comment\">--fts-ramsize 1024</span>\n</pre>\n<p>For more info, see <a href=\"https://developer.couchbase.com/documentation/server/current/install/sizing-general.html\" class=\"preview__body--description--blue\" target=\"_blank\">Sizing Couchbase Server\nResources</a>.</p>\n<h2 class=\"preview__body--subtitle\" id=\"debugging-tips-and-tricks\">Debugging tips and tricks</h2>\n<p>Some tips and tricks for debugging issues with your Couchbase cluster:</p>\n<ul>\n<li>Use <a href=\"/repos/v0.2.2/terraform-aws-couchbase/modules/run-couchbase-server/sdk-doctor\" class=\"preview__body--description--blue\">https://github.com/couchbaselabs/sdk-doctor</a> to diagnose connection issues.</li>\n<li>When using Couchbase SDK tools, set <code>LCB_LOGLEVEL=5</code> to get more logging output from Couchbase clients.</li>\n<li>Log file locations: https://developer.couchbase.com/documentation/server/3.x/admin/Misc/Trbl-logs.html.</li>\n<li>Use <code>systemctl status couchbase-server</code> to see if systemd thinks the Couchbase process is running.</li>\n</ul>\n","repoName":"terraform-aws-couchbase","repoRef":"v0.2.2","serviceDescriptor":{"serviceName":"Couchbase","serviceRepoName":"terraform-aws-couchbase","serviceRepoOrg":"gruntwork-io","cloudProviders":["aws"],"description":"Deploy a Couchbase cluster. Supports automatic bootstrapping, Sync Gateway, Web Console UI, cross-region replication, and auto healing.","imageUrl":"couchbase.png","licenseType":"open-source","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"NoSQL","fileName":"README.md","filePath":"/modules/run-couchbase-server","title":"Repo Browser: Couchbase","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
run-couchbase-server
