The local cluster setup on a single host is intended for development and learning. For production deployment, performance benchmarking, or deploying a true multi-node on multi-host setup, see [Deploy YugabyteDB](/stable/deploy/).
Note that the Docker option to run local clusters is recommended only for advanced Docker users. This is due to the fact that running stateful applications such as YugabyteDB in Docker is more complex and error-prone than running stateless applications.
## Install YugabyteDB
### Prerequisites
Before installing YugabyteDB, ensure that you have the Docker runtime installed on your localhost. To download and install Docker, select one of the following environments:
[Docker for Mac](https://store.docker.com/editions/community/docker-ce-desktop-mac)
[Docker for CentOS](https://store.docker.com/editions/community/docker-ce-server-centos)
[Docker for Ubuntu](https://store.docker.com/editions/community/docker-ce-server-ubuntu)
[Docker for Debian](https://store.docker.com/editions/community/docker-ce-server-debian)
[Docker for Windows](https://store.docker.com/editions/community/docker-ce-desktop-windows)
### Install
Pull the YugabyteDB container by executing the following command:
```sh
docker pull yugabytedb/yugabyte:{{< yb-version version="stable" format="build">}}
```
## Create a local cluster
Use the [yugabyted](/stable/reference/configuration/yugabyted/) utility to create and manage universes.
To create a 1-node cluster with a replication factor (RF) of 1, run the following command:
```sh
docker run -d --name yugabyte \
-p 7000:7000 -p 9000:9000 -p 15433:15433 -p 5433:5433 -p 9042:9042 \
yugabytedb/yugabyte:{{< yb-version version="stable" format="build">}} bin/yugabyted start \
--background=false
```
If you are running macOS Monterey, replace `-p 7000:7000` with `-p 7001:7000`. This is necessary because Monterey enables AirPlay receiving by default, which listens on port 7000. This conflicts with YugabyteDB and causes `yugabyted start` to fail unless you forward the port as shown. Alternatively, you can disable AirPlay receiving, then start YugabyteDB normally, and then, optionally, re-enable AirPlay receiving.
Run the following command to check the container status:
```sh
docker ps
```
```output
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c1c98c29149b yugabytedb/yugabyte:{{< yb-version version="stable" format="build">}} "/sbin/tini -- bin/y…" 7 seconds ago Up 5 seconds 0.0.0.0:5433->5433/tcp, 6379/tcp, 7100/tcp, 0.0.0.0:7000->7000/tcp, 0.0.0.0:9000->9000/tcp, 7200/tcp, 9100/tcp, 10100/tcp, 11000/tcp, 0.0.0.0:9042->9042/tcp, 0.0.0.0:15433->15433/tcp, 12000/tcp yugabyte
```
Run the following command to check the cluster status:
```sh
docker exec -it yugabyte yugabyted status
```
```output
+----------------------------------------------------------------------------------------------------------+
| yugabyted |
+----------------------------------------------------------------------------------------------------------+
| Status : Running. |
| Replication Factor : 1 |
| YugabyteDB UI : http://172.17.0.2:15433 |
| JDBC : jdbc:postgresql://172.17.0.2:5433/yugabyte?user=yugabyte&password=yugabyte |
| YSQL : bin/ysqlsh -h 172.17.0.2 -U yugabyte -d yugabyte |
| YCQL : bin/ycqlsh 172.17.0.2 9042 -u cassandra |
| Data Dir : /root/var/data |
| Log Dir : /root/var/logs |
| Universe UUID : f4bae205-4b4f-4dcc-9656-a04354cb9301 |
+----------------------------------------------------------------------------------------------------------+
```
### Run Docker in a persistent volume
In the preceding `docker run` command, the data stored in YugabyteDB does not persist across container restarts. To make YugabyteDB persist data across restarts, you can add a volume mount option to the docker run command, as follows:
- Create a `~/yb_data` directory by executing the following command:
```sh
mkdir ~/yb_data
```
- Run Docker with the volume mount option by executing the following command:
```sh
docker run -d --name yugabyte01 --hostname yugabyte01 \
-p 7000:7000 -p 9000:9000 -p 15433:15433 -p 5433:5433 -p 9042:9042 \
yugabytedb/yugabyte:{{< yb-version version="stable" format="build">}} bin/yugabyted start \
--base_dir=/home/yugabyte/yb_data \
--background=false
```
If running macOS Monterey, replace `-p 7000:7000` with `-p 7001:7000`.
{{< note title="Base directory" >}}
yugabyted uses `$HOME/var` by default to store data, configurations, and logs. You can change the base directory when starting a cluster using the `--base_dir` flag. If you change the base directory, you _must_ specify the base directory using the `--base-dir` flag when running subsequent commands on the cluster.
For example, to get the status of the cluster you just created, you would enter `bin/yugabyted status --base_dir=/home/yugabyte/yb_data`.
{{< /note >}}
{{< note title="Hostname" >}}
It is important to use a static container hostname to avoid startup errors if the hostname changes, such as when recreating the container with the same volume.
{{< /note >}}
## Connect to the database
The cluster you have created consists of two processes:
- [YB-Master](/stable/architecture/yb-master/) keeps track of various metadata (list of tables, users, roles, permissions, and so on).
- [YB-TServer](/stable/architecture/yb-tserver/) is responsible for the actual end user requests for data updates and queries.
Using the YugabyteDB SQL shell, [ysqlsh](/stable/api/ysqlsh/), you can connect to your cluster and interact with it using distributed SQL. ysqlsh is installed with YugabyteDB and is located in the bin directory of the YugabyteDB home directory.
To open the YSQL shell, run ysqlsh.
```sh
docker exec -it yugabyte bash -c '/home/yugabyte/bin/ysqlsh --echo-queries --host $(hostname)'
```
```output
ysqlsh (15.2-YB-{{}}-b0)
Type "help" for help.
yugabyte=#
```
To load sample data and explore an example using ysqlsh, refer to [Retail Analytics](/stable/sample-data/retail-analytics/).
## Monitor your cluster
When you start a cluster using yugabyted, you can monitor the cluster using the YugabyteDB UI, available at [localhost:15433](http://localhost:15433).
The YugabyteDB UI provides cluster status, node information, performance metrics, and more.
## Next steps
- [Explore YugabyteDB](/stable/explore/)
- [Develop for YugabyteDB](/stable/develop/)
Use a cloud cluster
Use a local cluster