How to Install Vitess Database: Step-by-Step Guide

Vitess is an open-source database clustering system designed for scaling MySQL databases horizontally. It is widely used for cloud-native applications requiring high availability, fault tolerance, and easy scaling. This tutorial will guide you through installing Vitess from scratch on a single machine for development or testing purposes. For production deployment, Vitess also supports Kubernetes and cloud environments.

Prerequisites

A Linux-based system (Ubuntu 20.04+ recommended)
Docker and Docker Compose installed (for simplified setup)
Basic knowledge of MySQL and Linux command line
Minimum 8GB RAM and 20GB free disk space
Git installed for cloning the Vitess repository

Step 1: Install Docker and Docker Compose

If you do not have Docker and Docker Compose installed, run the following commands:

sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker

Verify installation with:

docker --version
docker-compose --version

Step 2: Clone the Vitess Repository

Clone the official Vitess GitHub repository for latest stable code and examples:

git clone https://github.com/vitessio/vitess.git
cd vitess

Step 3: Setup Vitess Example Cluster with Docker Compose

Vitess provides an example Docker Compose file to start a local test cluster quickly.

Navigate to the ‘docker/local’ directory:

cd docker/local

Start the Vitess cluster using Docker Compose:

docker-compose up -d

This will launch the necessary components: Vitess topology service, MySQL instances, VTGate, and VTTablet processes.

Step 4: Verify Vitess Cluster is Running

Use the following command to list running containers related to Vitess:

docker ps | grep vitess

You should see containers for vtctld, vtgate, and tablets.

Step 5: Interact with Vitess SQL Layer

Vitess exposes a MySQL-compatible interface via VTGate. To connect:

Install the MySQL client if you don’t have it:

sudo apt install mysql-client

Connect using VTGate’s exposed port (default 15306):

mysql -h 127.0.0.1 -P 15306 -u user

Once connected, you can execute standard MySQL commands. The Vitess cluster will route queries to the appropriate shards transparently.

Step 6: Explore Vitess Management Tools

Vitess control is available via vtctld, which serves a UI and CLI to manage Vitess keyspaces and tablets. Open this in a browser at http://localhost:15000.

Troubleshooting

If Docker containers fail to start, check logs via docker-compose logs.
Make sure ports 15000, 15306, and 15999 are free and accessible.
Ensure Docker daemon is running and your user has permission to run Docker commands.
For advanced setups, consider configuring persistent storage and multi-node Vitess clusters.

Summary Checklist

Install Docker & Docker Compose
Clone Vitess GitHub repository
Launch example cluster with docker-compose
Verify all Vitess services are running
Connect to VTGate MySQL interface
Use vtctld for Vitess cluster management
Troubleshoot common Docker and network issues

Vitess simplifies scaling MySQL with transparent sharding and clustering for cloud applications. For extended tutorials and production deployment, you can explore our guide on How to Install MariaDB Galera Cluster to understand similar clustering concepts and apply cloud best practices.