Advanced setup
Contents:
Installing directly on Ubuntu, Debian, CentOS, or Fedora
Warning
There is no supported uninstallation process with the direct-install
method. If you want that, use the Vagrant environment,
where you can just do vagrant destroy
to clean up the development environment.
One can install the Zulip development environment directly on a Linux host by following these instructions. Currently supported platforms are:
Ubuntu 22.04, 24.04
Debian 12
CentOS 7 (beta)
Fedora 38 (beta)
RHEL 7 (beta)
Note: You should not use the root
user to run the installation.
If you are using a remote server, see
the
section on creating appropriate user accounts.
Start by cloning your fork of the Zulip repository and connecting the Zulip upstream repository:
git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git
cd zulip
git remote add -f upstream https://github.com/zulip/zulip.git
CentOS, Fedora, and RHEL users should ensure that python3 is installed on their systems (Debian and Ubuntu distributions already include it):
# On CentOS/Fedora/RHEL, you must first install python3.
# For example, this command installs python3 with yum:
yum install python
With python3 installed, change into the directory where you have cloned Zulip and run the following commands:
# From inside a clone of zulip.git:
./tools/provision
source /srv/zulip-py3-venv/bin/activate
./tools/run-dev # starts the development server
Once you’ve done the above setup, you can pick up the documentation
on using the Zulip development
environment,
ignoring the parts about vagrant
(since you’re not using it).
Installing using Vagrant with VirtualBox on Windows 10
Note
We recommend using WSL 2 for Windows development because it is easier to set up and provides a substantially better experience.
Install Git for Windows, which installs Git BASH.
Install VirtualBox (latest).
Install Vagrant (latest).
(Note: While Git BASH is recommended, you may also use Cygwin. If you do, make sure to install default required packages along with git, curl, openssh, and rsync binaries.)
Also, you must have hardware virtualization enabled (VT-x or AMD-V) in your computer’s BIOS.
Running Git BASH as an administrator
It is important that you always run Git BASH with administrator privileges when working on Zulip code, as not doing so will cause errors in the development environment (such as symlink creation). You might wish to configure your Git BASH shortcut to always run with these privileges enabled (see this guide for how to set this up).
Enable native symlinks
The Zulip code includes symbolic links (symlinks). By default, native Windows symlinks are not enabled in either Git BASH or Cygwin, so you need to do a bit of configuration. You must do this before you clone the Zulip code.
In Git for BASH:
Open Git BASH as an administrator and run:
$ git config --global core.symlinks true
Now confirm the setting:
$ git config core.symlinks
true
If you see true
, you are ready for Step 2: Get Zulip code.
Otherwise, if the above command prints false
or nothing at all, then symlinks
have not been enabled.
In Cygwin:
Open a Cygwin window as an administrator and do this:
christie@win10 ~
$ echo 'export "CYGWIN=$CYGWIN winsymlinks:native"' >> ~/.bash_profile
Next, close that Cygwin window and open another. If you echo
$CYGWIN you
should see:
christie@win10 ~
$ echo $CYGWIN
winsymlinks:native
Now you are ready for Step 2: Get Zulip code.
(Note: The GitHub Desktop client for Windows has a bug where it
will automatically set git config core.symlink false
on a repository
if you use it to clone a repository, which will break the Zulip
development environment, because we use symbolic links. For that
reason, we recommend avoiding using GitHub Desktop client to clone
projects and to instead follow these instructions exactly.)
Using the Vagrant Hyper-V provider on Windows (beta)
You should have Vagrant and Hyper-V installed on your system. Ensure they both work as expected.
NOTE: Hyper-V is available only on Windows Enterprise, Pro, or Education.
Start by cloning your fork of the Zulip repository and connecting the Zulip upstream repository:
git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git cd zulip git remote add -f upstream https://github.com/zulip/zulip.git
You will have to open up powershell with administrator rights in order to use Hyper-V. Then provision the development environment:
vagrant up --provider=hyperv
You should get output like this:
Bringing machine 'default' up with 'hyperv' provider... ==> default: Verifying Hyper-V is enabled... ==> default: Verifying Hyper-V is accessible... <other stuff>... ==> default: Waiting for the machine to report its IP address... default: Timeout: 120 seconds default: IP: 172.28.119.70 ==> default: Waiting for machine to boot. This may take a few minutes... default: SSH address: 172.28.122.156 ==> default: Machine booted and ready! ==> default: Preparing SMB shared folders... Vagrant requires administrator access for pruning SMB shares and may request access to complete removal of stale shares. ==> default: Starting the machine... <other stuff>... default: Username (user[@domain]): <your-machine-username> default: Password (will be hidden):
At this point, you will be prompted for your Windows administrator username and password (not your Microsoft account credentials).
SSH into your newly created virtual machine
vagrant ssh
This will ssh you into the bash shell of the Zulip development environment where you can execute bash commands.
Set the
EXTERNAL_HOST
environment variable.(zulip-py3-venv) vagrant@ubuntu-18:/srv/zulip$ export EXTERNAL_HOST="$(hostname -I | xargs):9991" (zulip-py3-venv) vagrant@ubuntu-18:/srv/zulip$ echo $EXTERNAL_HOST
The output will be like:
172.28.122.156:9991
Make sure you note down this down. This is where your zulip development web server can be accessed.
Important
The output of the above command changes every time you restart the Vagrant development machine. Thus, it will have to be run every time you bring one up. This quirk is one reason this method is marked experimental.
You should now be able to start the Zulip development server.
(zulip-py3-venv) vagrant@ubuntu-18:/srv/zulip$ ./tools/run-dev
The output will look like:
Starting Zulip on: http://172.30.24.235:9991/ Internal ports: 9991: Development server proxy (connect here) 9992: Django 9993: Tornado 9994: webpack
Visit the indicated URL in your web browser.
You can stop the development environment using
vagrant halt
, and restart it usingvagrant up
and then going through steps 3 and 4 again.
Problems you may encounter
If you get the error
Hyper-V could not initialize memory
, this is likely because your system has insufficient free memory to start the virtual machine. You can generally work around this error by closing all other running programs and runningvagrant up --provider=hyperv
again. You can reopen the other programs after the provisioning is completed. If it still isn’t enough, try restarting your system and running the command again.Be patient the first time you run
./tools/run-dev
.
As with other installation methods, please visit #provision help in the Zulip development community server if you need help.
Newer versions of supported platforms
You can use our provisioning tool to set up the Zulip development environment on current versions of these platforms reliably and easily, so we no longer maintain manual installation instructions for these platforms.
If tools/provision
doesn’t yet support a newer release of Debian or
Ubuntu that you’re using, we’d love to add support for it. It’s
likely only a few lines of changes to tools/lib/provision.py
and
scripts/lib/setup-apt-repo
if you’d like to do it yourself and
submit a pull request, or you can ask for help in
#development help
in the Zulip development community,
and a core team member can help guide you through adding support for the platform.