Install Couchbase Server on Linux, Windows, macOS or Docker, pick the right edition, initialise the cluster, and verify it by creating a bucket and running a query.
Installing Couchbase Server has two parts: install the package, then initialise the node as a cluster. Until the second step is done the server is running but unusable, which is where most first installs get stuck.
The fastest way to get a working single node is Docker:
docker run -d --name db -p 8091-8097:8091-8097 -p 11210-11211:11210-11211 couchbase/server
Then open http://localhost:8091 and choose Setup New Cluster. The sections below cover native installs on Linux, Windows and macOS, initialising from the command line, and checking that it works. The commands are for the current 8.0 release line.
Choose an edition first
Couchbase Server ships in two editions, and the package names differ.
Enterprise Edition
Community Edition
Licence
Commercial; needs a subscription for production use
Free to deploy, within limits
Cluster size
Not limited by the licence
Up to five nodes
CPU
Not limited by the licence
Uses at most 4 cores per node
Cross data center replication (XDCR)
Yes
No
Bug fixes
Maintenance releases and hot fixes
Does not receive the latest fixes
Linux package name
couchbase-server
couchbase-server-community
The default download, the default package and the default Docker image are all Enterprise Edition. If you want the free edition, select Community explicitly. Read the licence terms on Couchbase's site before putting either edition into production, because they have changed over time.
If you would rather not run servers at all, Couchbase Capella is the vendor's managed cloud service.
System requirements
Couchbase's documented minimum for a node is a 2-core 64-bit CPU, 4 GiB of RAM and 8 GiB of disk. The recommendation for production is 4 cores, 16 GiB of RAM or more, and SSD storage.
Supported platforms for the 8.0 line include Ubuntu 22.04 and 24.04, Debian 11 to 13, RHEL 8 to 10 and compatible distributions, Amazon Linux 2023, and Windows Server 2022 and 2025. Windows 11 and macOS are supported for development and testing only. All nodes in a cluster must run the same operating system and version.
Install on Ubuntu or Debian
Install Couchbase's repository package, then the server:
Use couchbase-server-community for Community Edition.
Install on Windows
Download the MSI package for your edition from the Couchbase downloads page.
Run it as an administrator. Accept the licence, choose the destination folder and install.
The server is registered as a Windows service that runs under the Local System account and starts automatically.
For an unattended install, the MSI accepts the standard quiet switch. From an elevated PowerShell window, in the folder that holds the download (replace the file name with the one you downloaded):
Couchbase's documentation advises disabling third-party antivirus during installation and uninstalling any earlier Couchbase version first.
Install on macOS
Download the macOS disk image, drag Couchbase Server to the Applications folder and open it. It runs as a menu-bar application, for development use only.
Docker details
The command at the top of the page publishes the web console and service ports (8091 to 8097) and the data port (11210). Two additions are worth making:
docker run -d --name db \
-p 8091-8097:8091-8097 -p 11210-11211:11210-11211 \
-v couchbase_data:/opt/couchbase/var \
couchbase:community
-v couchbase_data:/opt/couchbase/var keeps data and configuration in a named volume. Without it, removing the container removes the database.
couchbase:community selects Community Edition from the official Docker Hub image. The enterprise and latest tags are Enterprise Edition. Version-specific tags are available for both.
Initialise the cluster
Even a single node has to be set up as a cluster of one. You choose an administrator name and password, which services the node runs, and how much memory each service gets.
With the web console
Open http://localhost:8091 (or the server's address), click Setup New Cluster, enter a cluster name and administrator credentials, accept the terms, and either finish with defaults or configure memory quotas and services.
With the command line
couchbase-cli is in /opt/couchbase/bin on Linux and in the bin folder of the installation directory on Windows. With Docker, prefix the commands with docker exec db.
--cluster-ramsize and --cluster-index-ramsize are memory quotas in MiB for the Data and Index services. Lower them if the command reports that the quota exceeds the memory available, which is common in containers and small VMs.
Verify the installation
Create a bucket, which is the container for your documents:
USE KEYS fetches the document by its key, so the query works without creating an index. A query that filters on other fields needs an index first.
Ports and firewalls
Clients and other nodes must be able to reach these ports. Each has a TLS equivalent.
Port
TLS port
Used for
8091
18091
Web console and cluster management REST API
8092
18092
Views
8093
18093
Query service
8094
18094
Search service
8095
18095
Analytics service
8096
18096
Eventing service
8097
18097
Backup service
11210
11207
Data service: SDK clients and replication
Nodes in a cluster use further ports to talk to each other. The full list is in the documentation linked below. Do not expose any of these ports to the public internet.
Troubleshooting
The browser cannot open http://localhost:8091.
Check that the service is running (sudo systemctl status couchbase-server, docker ps, or the Services console on Windows). The server needs several seconds after starting before the console responds. With Docker, confirm that you published the ports with -p.
The console shows the setup wizard again after recreating a container.
The configuration lived inside the old container. Use a volume for /opt/couchbase/var.
couchbase-cli reports that the cluster is not initialised, or SDKs fail to authenticate.
The package is installed but cluster-init, or the web setup wizard, has not been run.
Memory quota errors during setup.
The total of all service quotas has to fit within the machine's RAM with room left for the operating system. Reduce the quotas or run fewer services on the node.
A query fails with "No index available on keyspace".
The Query service needs an index for anything other than key lookups. Create one with CREATE INDEX, or a primary index for experiments:
CREATEPRIMARY INDEX ON demo;
The web console works but the application times out when connecting.
Opening 8091 is not enough. SDKs talk directly to the Data service on 11210 (11207 with TLS) and to the service ports for queries and search. Open those as well.
Uninstall
Back up anything you need first. On Ubuntu and Debian:
On RHEL-based systems, replace the second line with sudo rpm -e couchbase-server. Use the couchbase-server-community package name if that is what you installed. On Windows, uninstall Couchbase Server from Settings > Apps, then delete the Couchbase folder under C:\Program Files. With Docker, run docker rm -f db and remove the volume with docker volume rm couchbase_data.
