mirror of https://github.com/zulip/zulip.git
docs: Fix development environment setup on Windows.
Windows users end up having to follow an odd chain of links because the recommended installation instructions live on a different page than the rest of the instructions about the environment setup. All the tutorials about recommended install prerequisites for each platform should be on the same page. This moves the section about using WSL 2 from the advanced setup page to the recommended environment setup tutorial page. Renames sidebar and section titles to more accurately reflect the information in the Recommended setup vs. the Advanced setup page. Updates relevant text and links accordingly. Fixes: #13696.
This commit is contained in:
David Rosa
Tim Abbott
parent
948dc3a629
commit
cdc9a64c21
|
|
@ -6,8 +6,8 @@ maxdepth: 3
|
|||
---
|
||||
|
||||
Development environment installation <overview>
|
||||
Recommended setup (Vagrant) <setup-vagrant>
|
||||
Advanced setup (non-Vagrant) <setup-advanced>
|
||||
Recommended setup <setup-vagrant>
|
||||
Advanced setup <setup-advanced>
|
||||
Using the development environment <using>
|
||||
Developing remotely <remote>
|
||||
Authentication in the development environment <authentication>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
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. 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 WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment).
|
||||
|
||||
1. Launch the Ubuntu shell as an administrator and run the following command:
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
|
||||
1. Install dependencies with the following command:
|
||||
|
||||
```bash
|
||||
sudo apt install rabbitmq-server memcached redis-server postgresql
|
||||
```
|
||||
|
||||
1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/rabbitmq/rabbitmq-env.conf
|
||||
```
|
||||
|
||||
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`).
|
||||
|
||||
```ini
|
||||
NODE_IP_ADDRESS=127.0.0.1
|
||||
NODE_PORT=5672
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
cd ~ # or cd /home/USERNAME
|
||||
```
|
||||
|
||||
1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of
|
||||
the [Zulip server repository](https://github.com/zulip/zulip).
|
||||
|
||||
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.
|
||||
|
||||
1. Clone and connect to the Zulip upstream repository:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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`.)
|
||||
|
||||
```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
|
||||
```
|
||||
## Installing using Vagrant with VirtualBox on Windows 10
|
||||
|
||||
:::{note}
|
||||
If you shut down WSL, after starting it again, you will have to manually start
|
||||
the services using `./tools/wsl/start_services`.
|
||||
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. If you are facing problems or you see error messages after running `./tools/run-dev.py`,
|
||||
you can try running `./tools/provision` again.
|
||||
1. Install [Git for Windows][git-bash], which installs _Git BASH_.
|
||||
2. Install [VirtualBox][vbox-dl] (latest).
|
||||
3. Install [Vagrant][vagrant-dl] (latest).
|
||||
|
||||
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: 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.)
|
||||
|
||||
```bash
|
||||
code .
|
||||
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][bash-admin-setup] 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:
|
||||
|
||||
```console
|
||||
$ git config --global core.symlinks true
|
||||
```
|
||||
|
||||
to open VSCode connected to your WSL environment.
|
||||
Now confirm the setting:
|
||||
|
||||
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).
|
||||
```console
|
||||
$ git config core.symlinks
|
||||
true
|
||||
```
|
||||
|
||||
WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]
|
||||
If you see `true`, you are ready for [Step 2: Get Zulip code](setup-vagrant.md#step-2-get-zulip-code).
|
||||
|
||||
[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
|
||||
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:
|
||||
|
||||
```console
|
||||
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:
|
||||
|
||||
```console
|
||||
christie@win10 ~
|
||||
$ echo $CYGWIN
|
||||
winsymlinks:native
|
||||
```
|
||||
|
||||
Now you are ready for [Step 2: Get Zulip code](setup-vagrant.md#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.)
|
||||
|
||||
[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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
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. 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 WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment).
|
||||
|
||||
1. Launch the Ubuntu shell as an administrator and run the following command:
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade
|
||||
```
|
||||
|
||||
1. Install dependencies with the following command:
|
||||
|
||||
```bash
|
||||
sudo apt install rabbitmq-server memcached redis-server postgresql
|
||||
```
|
||||
|
||||
1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/rabbitmq/rabbitmq-env.conf
|
||||
```
|
||||
|
||||
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`).
|
||||
|
||||
```ini
|
||||
NODE_IP_ADDRESS=127.0.0.1
|
||||
NODE_PORT=5672
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
cd ~ # or cd /home/USERNAME
|
||||
```
|
||||
|
||||
1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of
|
||||
the [Zulip server repository](https://github.com/zulip/zulip).
|
||||
|
||||
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.
|
||||
|
||||
1. Clone and connect to the Zulip upstream repository:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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`.)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
:::{note}
|
||||
We recommend using [WSL 2 for Windows development](setup-advanced.md#installing-directly-on-windows-10-with-wsl-2).
|
||||
If you shut down WSL, after starting it again, you will have to manually start
|
||||
the services using `./tools/wsl/start_services`.
|
||||
:::
|
||||
|
||||
1. Install [Git for Windows][git-bash], which installs _Git BASH_.
|
||||
2. Install [VirtualBox][vbox-dl] (latest).
|
||||
3. Install [Vagrant][vagrant-dl] (latest).
|
||||
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: 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. 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:
|
||||
|
||||
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][bash-admin-setup] 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:
|
||||
|
||||
```console
|
||||
$ git config --global core.symlinks true
|
||||
```bash
|
||||
code .
|
||||
```
|
||||
|
||||
Now confirm the setting:
|
||||
to open VSCode connected to your WSL environment.
|
||||
|
||||
```console
|
||||
$ git config core.symlinks
|
||||
true
|
||||
```
|
||||
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).
|
||||
|
||||
If you see `true`, you are ready for [Step 2: Get Zulip
|
||||
code](#step-2-get-zulip-code).
|
||||
WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]
|
||||
|
||||
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:
|
||||
|
||||
```console
|
||||
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:
|
||||
|
||||
```console
|
||||
christie@win10 ~
|
||||
$ echo $CYGWIN
|
||||
winsymlinks:native
|
||||
```
|
||||
|
||||
Now you are ready for [Step 2: Get Zulip code](#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.)
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue