diff --git a/docs/development/index.md b/docs/development/index.md index 40075452fb..38e93839b4 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -6,8 +6,8 @@ maxdepth: 3 --- Development environment installation -Recommended setup (Vagrant) -Advanced setup (non-Vagrant) +Recommended setup +Advanced setup Using the development environment Developing remotely Authentication in the development environment diff --git a/docs/development/overview.md b/docs/development/overview.md index efe311808f..917524007e 100644 --- a/docs/development/overview.md +++ b/docs/development/overview.md @@ -84,4 +84,4 @@ machine, take a look at our tips for [using-dev-env]: using.md [testing]: ../testing/testing.md [ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork -[install-via-wsl]: setup-advanced.md#installing-directly-on-windows-10-with-wsl-2 +[install-via-wsl]: setup-vagrant.md#windows-10 diff --git a/docs/development/setup-advanced.md b/docs/development/setup-advanced.md index b400ecf0b5..f947a393ee 100644 --- a/docs/development/setup-advanced.md +++ b/docs/development/setup-advanced.md @@ -3,7 +3,7 @@ Contents: - [Installing directly on Ubuntu, Debian, CentOS, or Fedora](#installing-directly-on-ubuntu-debian-centos-or-fedora) -- [Installing directly on Windows 10 with WSL 2](#installing-directly-on-windows-10-with-wsl-2) +- [Installing using Vagrant with VirtualBox on Windows 10](#installing-using-vagrant-with-virtualbox-on-windows-10) - [Using the Vagrant Hyper-V provider on Windows](#using-the-vagrant-hyper-v-provider-on-windows-beta) - [Newer versions of supported platforms](#newer-versions-of-supported-platforms) @@ -53,112 +53,91 @@ on using the Zulip development environment](setup-vagrant.md#step-4-developing), ignoring the parts about `vagrant` (since you're not using it). -## Installing directly on Windows 10 with WSL 2 +## Installing using Vagrant with VirtualBox on Windows 10 -Zulip's development environment is most easily set up on Windows using -the Windows Subsystem for Linux ([WSL -2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about)) -installation method described here. +:::{note} +We recommend using [WSL 2 for Windows development](setup-vagrant.md#windows-10) +because it is easier to set up and provides a substantially better experience. +::: -1. Enable virtualization through your BIOS settings. This sequence - depends on your specific hardware and brand, but here are [some - basic instructions.][windows-bios-virtualization] +1. Install [Git for Windows][git-bash], which installs _Git BASH_. +2. Install [VirtualBox][vbox-dl] (latest). +3. Install [Vagrant][vagrant-dl] (latest). -1. [Install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment). +(Note: While _Git BASH_ is recommended, you may also use [Cygwin][cygwin-dl]. +If you do, make sure to **install default required packages** along with +**git**, **curl**, **openssh**, and **rsync** binaries.) -1. Launch the Ubuntu shell as an administrator and run the following command: +Also, you must have hardware virtualization enabled (VT-x or AMD-V) in your +computer's BIOS. - ```bash - sudo apt update && sudo apt upgrade - ``` +#### Running Git BASH as an administrator -1. Install dependencies with the following command: +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][bash-admin-setup] for how +to set this up). - ```bash - sudo apt install rabbitmq-server memcached redis-server postgresql - ``` +##### Enable native symlinks -1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.: +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.** - ```bash - sudo nano /etc/rabbitmq/rabbitmq-env.conf - ``` +In **Git for BASH**: - Confirm the following lines are at the end of your file, and add - them if not present. Then save your changes (`Ctrl+O`, then `Enter` - to confirm the path), and exit `nano` (`Ctrl+X`). +Open **Git BASH as an administrator** and run: - ```ini - NODE_IP_ADDRESS=127.0.0.1 - NODE_PORT=5672 - ``` +```console +$ git config --global core.symlinks true +``` -1. Run the command below to make sure you are inside the WSL disk and not in a Windows mounted disk. - You will run into permission issues if you run `provision` from `zulip` - in a Windows mounted disk. +Now confirm the setting: - ```bash - cd ~ # or cd /home/USERNAME - ``` +```console +$ git config core.symlinks +true +``` -1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of - the [Zulip server repository](https://github.com/zulip/zulip). +If you see `true`, you are ready for [Step 2: Get Zulip code](setup-vagrant.md#step-2-get-zulip-code). -1. [Create a new SSH key][create-ssh-key] for the WSL-2 Virtual - Machine and add it to your GitHub account. Note that SSH keys - linked to your Windows computer will not work within the virtual - machine. +Otherwise, if the above command prints `false` or nothing at all, then symlinks +have not been enabled. -1. Clone and connect to the Zulip upstream repository: +In **Cygwin**: - ```bash - git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git ~/zulip - cd zulip - git remote add -f upstream https://github.com/zulip/zulip.git - ``` +Open a Cygwin window **as an administrator** and do this: -1. Run the following to install the Zulip development environment and - start it. (If Windows Firewall creates popups to block services, simply click `Allow Access`.) +```console +christie@win10 ~ +$ echo 'export "CYGWIN=$CYGWIN winsymlinks:native"' >> ~/.bash_profile +``` - ```bash - # Start database, cache, and other services - ./tools/wsl/start_services - # Install/update the Zulip development environment - ./tools/provision - # Enter the Zulip Python environment - source /srv/zulip-py3-venv/bin/activate - # Start the development server - ./tools/run-dev.py - ``` +Next, close that Cygwin window and open another. If you `echo` $CYGWIN you +should see: - :::{note} - If you shut down WSL, after starting it again, you will have to manually start - the services using `./tools/wsl/start_services`. - ::: +```console +christie@win10 ~ +$ echo $CYGWIN +winsymlinks:native +``` -1. If you are facing problems or you see error messages after running `./tools/run-dev.py`, - you can try running `./tools/provision` again. +Now you are ready for [Step 2: Get Zulip code](setup-vagrant.md#step-2-get-zulip-code). -1. The [Visual Studio Code Remote - - WSL](https://code.visualstudio.com/docs/remote/wsl) extension is - recommended for editing files when developing with WSL. When you - have it installed, you can run: +(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.) - ```bash - code . - ``` - - to open VSCode connected to your WSL environment. - -1. You're done! You can pick up the [documentation on using the - Zulip development environment](setup-vagrant.md#step-4-developing), - ignoring the parts about `vagrant` (since you're not using it). - -WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl] - -[create-ssh-key]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account -[uninstall-wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution- -[windows-bios-virtualization]: https://www.thewindowsclub.com/disable-hardware-virtualization-in-windows-10 +[cygwin-dl]: https://cygwin.com +[git-bash]: https://git-for-windows.github.io +[vbox-dl]: https://www.virtualbox.org/wiki/Downloads +[vagrant-dl]: https://www.vagrantup.com/downloads.html +[bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10 ## Using the Vagrant Hyper-V provider on Windows (beta) diff --git a/docs/development/setup-vagrant.md b/docs/development/setup-vagrant.md index 3cfb046d38..8580fba04f 100644 --- a/docs/development/setup-vagrant.md +++ b/docs/development/setup-vagrant.md @@ -1,13 +1,13 @@ -## Vagrant environment setup tutorial +## Recommended environment setup tutorial This section guides first-time contributors through installing the Zulip development environment on Windows, macOS, and Linux. -The recommended method for installing the Zulip development environment is to use -Vagrant with VirtualBox on Windows, and Vagrant with Docker on -macOS and Linux. This method creates a virtual machine (for Windows) -or a Linux container (for macOS and Linux) inside which the Zulip server and -all related services will run. +The recommended method for installing the Zulip development environment is +to use WSL 2 on Windows, and Vagrant with Docker on macOS and Linux. +This methoduses the Windows Subsystem for Linux or creates a Linux container +(for macOS and Linux) inside which the Zulip server and all related +services will run. Contents: @@ -47,7 +47,8 @@ an active internet connection throughout the entire installation processes. (See [Specifying a proxy](#specifying-a-proxy) if you need a proxy to access the internet.) -- **All**: 2GB available RAM, Active broadband internet connection, [GitHub account][set-up-git]. +- **All**: 2GB available RAM, Active broadband internet connection, + [GitHub account](#step-0-set-up-git--github). - **macOS**: macOS (10.11 El Capitan or newer recommended) - **Ubuntu LTS**: 20.04 or 22.04 - **Debian**: 11 @@ -158,83 +159,109 @@ docker distribution, you can follow #### Windows 10 -:::{note} -We recommend using [WSL 2 for Windows development](setup-advanced.md#installing-directly-on-windows-10-with-wsl-2). -::: +Zulip's development environment is most easily set up on Windows using +the Windows Subsystem for Linux ([WSL +2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about)) +installation method described here. -1. Install [Git for Windows][git-bash], which installs _Git BASH_. -2. Install [VirtualBox][vbox-dl] (latest). -3. Install [Vagrant][vagrant-dl] (latest). +1. Enable virtualization through your BIOS settings. This sequence + depends on your specific hardware and brand, but here are [some + basic instructions.][windows-bios-virtualization] -(Note: While _Git BASH_ is recommended, you may also use [Cygwin][cygwin-dl]. -If you do, make sure to **install default required packages** along with -**git**, **curl**, **openssh**, and **rsync** binaries.) +1. [Install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment). -Also, you must have hardware virtualization enabled (VT-x or AMD-V) in your -computer's BIOS. +1. Launch the Ubuntu shell as an administrator and run the following command: -#### Running Git BASH as an administrator + ```bash + sudo apt update && sudo apt upgrade + ``` -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][bash-admin-setup] for how -to set this up). +1. Install dependencies with the following command: -##### Enable native symlinks + ```bash + sudo apt install rabbitmq-server memcached redis-server postgresql + ``` -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.** +1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.: -In **Git for BASH**: + ```bash + sudo nano /etc/rabbitmq/rabbitmq-env.conf + ``` -Open **Git BASH as an administrator** and run: + Confirm the following lines are at the end of your file, and add + them if not present. Then save your changes (`Ctrl+O`, then `Enter` + to confirm the path), and exit `nano` (`Ctrl+X`). -```console -$ git config --global core.symlinks true -``` + ```ini + NODE_IP_ADDRESS=127.0.0.1 + NODE_PORT=5672 + ``` -Now confirm the setting: +1. Run the command below to make sure you are inside the WSL disk and not + in a Windows mounted disk. You will run into permission issues if you + run `provision` from `zulip` in a Windows mounted disk. -```console -$ git config core.symlinks -true -``` + ```bash + cd ~ # or cd /home/USERNAME + ``` -If you see `true`, you are ready for [Step 2: Get Zulip -code](#step-2-get-zulip-code). +1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of + the [Zulip server repository](https://github.com/zulip/zulip). -Otherwise, if the above command prints `false` or nothing at all, then symlinks -have not been enabled. +1. [Create a new SSH key][create-ssh-key] for the WSL-2 Virtual + Machine and add it to your GitHub account. Note that SSH keys + linked to your Windows computer will not work within the virtual + machine. -In **Cygwin**: +1. Clone and connect to the Zulip upstream repository: -Open a Cygwin window **as an administrator** and do this: + ```bash + git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git ~/zulip + cd zulip + git remote add -f upstream https://github.com/zulip/zulip.git + ``` -```console -christie@win10 ~ -$ echo 'export "CYGWIN=$CYGWIN winsymlinks:native"' >> ~/.bash_profile -``` +1. Run the following to install the Zulip development environment and + start it. (If Windows Firewall creates popups to block services, simply click `Allow Access`.) -Next, close that Cygwin window and open another. If you `echo` $CYGWIN you -should see: + ```bash + # Start database, cache, and other services + ./tools/wsl/start_services + # Install/update the Zulip development environment + ./tools/provision + # Enter the Zulip Python environment + source /srv/zulip-py3-venv/bin/activate + # Start the development server + ./tools/run-dev.py + ``` -```console -christie@win10 ~ -$ echo $CYGWIN -winsymlinks:native -``` + :::{note} + If you shut down WSL, after starting it again, you will have to manually start + the services using `./tools/wsl/start_services`. + ::: -Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code). +1. If you are facing problems or you see error messages after running `./tools/run-dev.py`, + you can try running `./tools/provision` again. -(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.) +1. The [Visual Studio Code Remote - + WSL](https://code.visualstudio.com/docs/remote/wsl) extension is + recommended for editing files when developing with WSL. When you + have it installed, you can run: + + ```bash + code . + ``` + + to open VSCode connected to your WSL environment. + +1. You're done! Now you're ready for [Step 4: Developing](#step-4-developing), + ignoring the parts about `vagrant` (since you're not using it). + +WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl] + +[create-ssh-key]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account +[uninstall-wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution- +[windows-bios-virtualization]: https://www.thewindowsclub.com/disable-hardware-virtualization-in-windows-10 ### Step 2: Get Zulip code @@ -1046,15 +1073,11 @@ If at any time you wish to revert back to the default settings, simply remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from `~/.zulip-vagrant-config`. -[cygwin-dl]: https://cygwin.com/ [vagrant-dl]: https://www.vagrantup.com/downloads.html -[vbox-dl]: https://www.virtualbox.org/wiki/Downloads [install-advanced]: setup-advanced.md [rtd-git-guide]: ../git/index.md [rtd-testing]: ../testing/testing.md [rtd-using-dev-env]: using.md [rtd-dev-remote]: remote.md -[git-bash]: https://git-for-windows.github.io/ -[bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10 [set-up-git]: ../git/setup.md [ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork diff --git a/docs/git/cloning.md b/docs/git/cloning.md index 676d67b179..4900ffde2d 100644 --- a/docs/git/cloning.md +++ b/docs/git/cloning.md @@ -99,6 +99,9 @@ If you haven't already, now is a good time to install the Zulip development envi source projects in general, we recommend following our [detailed guide for first-time contributors][zulip-rtd-dev-first-time]. +If you are in the middle of installing the recommended setup on Windows 10, +you are ready to [continue with step 8](../development/setup-vagrant.md#windows-10). + ## Step 3: Configure continuous integration for your fork This step is optional, but recommended. diff --git a/docs/git/setup.md b/docs/git/setup.md index de41fa3762..38544b5ebe 100644 --- a/docs/git/setup.md +++ b/docs/git/setup.md @@ -8,8 +8,9 @@ can skip this section. Otherwise, read on! If you're not already using Git, you might need to [install][gitbook-install] and [configure][gitbook-setup] it. -**If you are using Windows 10, make sure you [are running Git BASH as an -administrator][git-bash-admin] at all times.** +**If you are using Windows 10 without [WSL +2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about), make sure you +[are running Git BASH as an administrator][git-bash-admin] at all times.** You'll also need a GitHub account, which you can sign up for [here][github-join]. @@ -29,6 +30,9 @@ We also highly recommend the following: - Install the command auto-completion and/or git-prompt plugins available for [Bash][gitbook-other-envs-bash] and [Zsh][gitbook-other-envs-zsh]. +If you are installing the Zulip development environment, now you are ready to +continue with [Step 1: Install prerequisites](../development/setup-vagrant.md#step-1-install-prerequisites). + ## Get a graphical client Even if you're comfortable using Git on the command line, having a graphical @@ -49,7 +53,7 @@ text-mode interface to Git. And, if none of the above are to your liking, try [one of these][gitbook-guis]. -[git-bash-admin]: ../development/setup-vagrant.md#running-git-bash-as-an-administrator +[git-bash-admin]: ../development/setup-advanced.md#running-git-bash-as-an-administrator [gitbook-aliases]: https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases [gitbook-config]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration [gitbook-guis]: https://git-scm.com/downloads/guis