The following has been verified to work on Ubuntu 19.10 and Debian 10. If you are new to Vitess, it is recommended to start with the local install guide instead.

Install Dependencies #

Install Go #

Download and install Golang. For example for go1.20.2, at writing:

curl -LO https://dl.google.com/go/go1.20.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.2.linux-amd64.tar.gz

Vitess is tested and shipped using a specific Golang version for each release. For maximum compatibility we encourage you to use the same Golang version as the one mentioned in our build.env file.

Make sure to add go to your bashrc:

# Additions to ~/.bashrc file

# Add go PATH
export PATH=$PATH:/usr/local/go/bin

# Add GOROOT
export GOROOT=/usr/local/go/

# Add GOPATH
export GOPATH=/home/<user>/go

Install Node 16.13.0+ #

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Ensure the following is in your bashrc/zshrc or similar:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Finally, install node:

nvm install --lts 16.13.0
nvm use 16.13.0

See the vtadmin README for more details.

Packages from apt repos #

Install dependencies required to build and run Vitess:

# Ubuntu
sudo apt-get install -y mysql-server mysql-client make unzip g++ etcd curl git wget

# Debian
sudo apt-get install -y default-mysql-server default-mysql-client make unzip g++ etcd curl wget

The services mysqld and etcd should be shutdown, since etcd will conflict with the etcd started in the examples, and mysqlctl will start its own copies of mysqld:

sudo service mysql stop
sudo service etcd stop
sudo systemctl disable mysql
sudo systemctl disable etcd

Notes:

• We will be using etcd as the topology service. The command make tools can also install Zookeeper or Consul for you, which requires additional dependencies.

Disable mysqld AppArmor Profile #

The mysqld AppArmor profile will not allow Vitess to launch MySQL in any data directory by default. You will need to disable it:

sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld

The following command should return an empty result:

sudo aa-status | grep mysqld

Build Vitess #

Navigate to the directory where you want to download the Vitess source code and clone the Vitess GitHub repo:

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

Set environment variables that Vitess will require. It is recommended to put these in your .bashrc:

# Additions to ~/.bashrc file

#VTDATAROOT
export VTDATAROOT=/tmp/vtdataroot

# Vitess binaries
export PATH=~/vitess/bin:${PATH}

Build Vitess:

make build

Since the addition of #13263 the vtadmin React application will be built when doing a make build. You can skip this step by setting the NOVTADMINBUILD environment variable.

NOVTADMINBUILD=1 make build

Testing your Binaries #

The unit test requires that you first install the following packages:

sudo apt-get install -y ant maven default-jdk zip

You can then install additional components from make tools. If your machine requires a proxy to access the Internet, you will need to set the usual environment variables (e.g. http_proxy, https_proxy, no_proxy) first:

make tools
make unit_test

In addition to running tests, you can try running the local example.

Common Build Issues #

Key Already Exists #

This error is because etcd was not cleaned up from the previous run of the example. You can manually fix this by running ./401_teardown.sh, removing vtdataroot and then starting again:

Error:  105: Key already exists (/vitess/zone1) [6]
Error:  105: Key already exists (/vitess/global) [6]

MySQL Fails to Initialize #

This error is most likely the result of an AppArmor enforcing profile being present:

1027 18:28:23.462926   19486 mysqld.go:734] mysqld --initialize-insecure failed: /usr/sbin/mysqld: exit status 1, output: mysqld: [ERROR] Failed to open required defaults file: /home/morgo/vitess/vtdataroot/vt_0000000102/my.cnf
mysqld: [ERROR] Fatal error in defaults handling. Program aborted!

could not stat mysql error log (/home/morgo/vitess/vtdataroot/vt_0000000102/error.log): stat /home/morgo/vitess/vtdataroot/vt_0000000102/error.log: no such file or directory
E1027 18:28:23.464117   19486 mysqlctl.go:254] failed init mysql: /usr/sbin/mysqld: exit status 1, output: mysqld: [ERROR] Failed to open required defaults file: /home/morgo/vitess/vtdataroot/vt_0000000102/my.cnf
mysqld: [ERROR] Fatal error in defaults handling. Program aborted!
E1027 18:28:23.464780   19483 mysqld.go:734] mysqld --initialize-insecure failed: /usr/sbin/mysqld: exit status 1, output: mysqld: [ERROR] Failed to open required defaults file: /home/morgo/vitess/vtdataroot/vt_0000000101/my.cnf
mysqld: [ERROR] Fatal error in defaults handling. Program aborted!

The following command disables the AppArmor profile for mysqld:

sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld

The following command should now return an empty result:

sudo aa-status | grep mysqld

If this doesn't work, you can try making sure all lurking processes are shutdown, and then restart the example again in the /tmp directory:

for process in `pgrep -f '(vtdataroot|VTDATAROOT)'`; do 
 kill -9 $process
done;

export VTDATAROOT=/tmp/vtdataroot
./101_initial_cluster.sh

Mysqlctl Fails to Start #

This error is because some tests need VTROOT, but it is missing. You can manually run source dev.env to solve this:

Running tool: /usr/local/go/bin/go test -timeout 30s -run ^TestFloatFormatting$ vitess.io/vitess/go/vt/vtgate/evalengine/integration

E0316 20:47:00.173050   63268 local_cluster.go:313] Mysqlctl failed to start: fork/exec bin/mysqlctl: no such file or directory
could not launch mysql: fork/exec bin/mysqlctl: no such file or directory
FAIL    vitess.io/vitess/go/vt/vtgate/evalengine/integration    0.018s

If you use an IDE to run these tests, you need to set VTROOT previously. For example, in VScode

"go.testEnvVars": {
    "VTROOT": "<path to my vitess checkout>"
}