From eb2f1b478885ea5a3344c6fae58d53ece2b46d26 Mon Sep 17 00:00:00 2001 From: Robert Dyer Date: Tue, 12 Mar 2024 14:28:44 -0500 Subject: [PATCH] docs: Upgrade development environment page to use synced tabs. This greatly reduces how much content for other platforms a reader has to scroll past in order to get the development environment set up. --- docs/development/overview.md | 2 +- docs/development/setup-advanced.md | 2 +- docs/development/setup-recommended.md | 568 ++++++++++++++++++----- docs/development/setup/vagrant-up.md | 3 +- docs/development/setup/vscode-vagrant.md | 34 ++ docs/git/cloning.md | 3 - 6 files changed, 486 insertions(+), 126 deletions(-) create mode 100644 docs/development/setup/vscode-vagrant.md diff --git a/docs/development/overview.md b/docs/development/overview.md index bf7c8497f4..ab7532284a 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-recommended.md#windows-10-or-11 +[install-via-wsl]: setup-recommended.md diff --git a/docs/development/setup-advanced.md b/docs/development/setup-advanced.md index a531d386eb..97cc00cb4d 100644 --- a/docs/development/setup-advanced.md +++ b/docs/development/setup-advanced.md @@ -66,7 +66,7 @@ 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](setup-recommended.md#windows-10-or-11) +We recommend using [WSL 2 for Windows development](setup-recommended.md) because it is easier to set up and provides a substantially better experience. ::: diff --git a/docs/development/setup-recommended.md b/docs/development/setup-recommended.md index 4788f0b04e..1e580b981f 100644 --- a/docs/development/setup-recommended.md +++ b/docs/development/setup-recommended.md @@ -41,20 +41,47 @@ When reporting your issue, please include the following information: ### Requirements -Installing the Zulip development environment with Vagrant requires -downloading several hundred megabytes of dependencies. You will need -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.) +Installing the Zulip development environment requires downloading several +hundred megabytes of dependencies. You will need 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](#step-0-set-up-git--github). -- **macOS**: macOS (10.11 El Capitan or newer recommended) -- **Ubuntu LTS**: 20.04, 22.04, or 24.04 -- **Debian**: 11 or 12 -- **Fedora**: tested for 36 -- **Windows**: Windows 64-bit (Windows 10 recommended), hardware - virtualization enabled (VT-x or AMD-V), administrator access. +- 2GB available RAM +- active broadband internet connection +- [GitHub account](#step-0-set-up-git--github) + +::::{tab-set} + +:::{tab-item} Windows +:sync: os-windows +:name: windows-10-or-11 + +- Windows 64-bit (Windows 10 recommended) +- hardware virtualization enabled (VT-x or AMD-V) +- administrator access + ::: + +:::{tab-item} macOS +:sync: os-mac + +- macOS (10.11 El Capitan or newer recommended) + ::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +- Ubuntu 20.04, 22.04, or 24.04 +- Debian 11 or 12 + ::: + +:::{tab-item} Fedora +:sync: os-fedora + +- tested for Fedora 36 + ::: + +:::: Other Linux distributions work great too, but we don't maintain documentation for installing Vagrant and Docker on those systems, so @@ -73,50 +100,10 @@ GitHub account using ### Step 1: Install prerequisites -Jump to: +::::{tab-set} -- [macOS](#macos) -- [Ubuntu](#ubuntu) -- [Debian](#debian) -- [Fedora](#fedora) -- [Windows](#windows-10-or-11) - -#### macOS - -1. Install [Vagrant][vagrant-dl] (latest). -2. Install [Docker Desktop](https://docs.docker.com/desktop/mac/install/) (latest). - -Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code). - -#### Ubuntu - -##### 1. Install Vagrant, Docker, and Git - -```console -$ sudo apt install vagrant docker.io git -``` - -```{include} setup/install-docker.md - -``` - -Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code). - -#### Debian - -The setup for Debian is the same as that [for Ubuntu above](#ubuntu). - -#### Fedora - -The setup for Fedora is mostly equivalent to the [setup for Ubuntu](#ubuntu). -The only difference is the installation of Docker. Fedora does not include the -official `docker-ce` package (named `docker.io` in the -[setup for Ubuntu](#ubuntu)) in their repositories. They provide the package -`moby-engine` which you can choose instead. In case you prefer the official -docker distribution, you can follow -[their documentation to install Docker on Fedora](https://docs.docker.com/engine/install/fedora/). - -#### Windows 10 or 11 +:::{tab-item} Windows +:sync: os-windows Zulip's development environment is most easily set up on Windows using the Windows Subsystem for Linux ([WSL @@ -152,14 +139,16 @@ installation method described here. We require version 0.67.6+ of WSL 2. ``` 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`). + them if not present: ```ini NODE_IP_ADDRESS=127.0.0.1 NODE_PORT=5672 ``` + Then save your changes (`Ctrl+O`, then `Enter` to confirm the path), + and exit `nano` (`Ctrl+X`). + 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 `./tools/provision` from `zulip` in a Windows mounted disk. @@ -168,58 +157,64 @@ installation method described here. We require version 0.67.6+ of WSL 2. $ 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: - - ```console - $ 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**.) - - ```console - $ # 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 - ``` - -1. If you are facing problems or you see error messages after running `./tools/run-dev`, - you can try running `./tools/provision` again. - -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: - - ```console - $ code . - ``` - - to open VS Code 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- +[uninstall-wsl]: https://learn.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 +::: + +:::{tab-item} macOS +:sync: os-mac + +1. Install [Vagrant][vagrant-dl] (latest). +2. Install [Docker Desktop](https://docs.docker.com/desktop/mac/install/) (latest). + ::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +##### 1. Install Vagrant, Docker, and Git + +```console +$ sudo apt install vagrant docker.io git +``` + +```{include} setup/install-docker.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +##### 1. Install Vagrant, Docker, and Git + +```console +$ sudo yum install vagrant git moby-engine +``` + +Fedora does not include the +official `docker-ce` package in their repositories. They provide the package +`moby-engine` which you can choose instead. In case you prefer the official +docker distribution, you can follow +[their documentation to install Docker on Fedora](https://docs.docker.com/engine/install/fedora/). + +```{include} setup/install-docker.md + +``` + +::: + +:::: + ### Step 2: Get Zulip code 1. In your browser, visit @@ -254,35 +249,42 @@ Checking connectivity... done. Checking out files: 100% (1912/1912), done. ``` -Now you are ready for [Step 3: Start the development -environment](#step-3-start-the-development-environment). - ### Step 3: Start the development environment +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + +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 +$ # 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 +``` + +If you are facing problems or you see error messages after running `./tools/run-dev`, +you can try running `./tools/provision` again. +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + Change into the zulip directory and tell Vagrant to start the Zulip development environment with `vagrant up`: ```console -$ # On Windows: $ cd zulip $ vagrant plugin install vagrant-vbguest $ vagrant up --provider=virtualbox - -$ # On macOS or Linux: -$ cd zulip -$ vagrant up --provider=docker ``` -:::{warning} -There is a [known upstream issue on macOS](https://chat.zulip.org/#narrow/stream/21-provision-help/topic/provision.20error.20ERR_PNPM_LINKING_FAILED/near/1649241) -that can cause provisioning to fail with `ERR_PNPM_LINKING_FAILED` or other errors. The temporary -fix is to open the Docker desktop app's settings panel, and choose `osxfs (legacy)` under "Choose -file sharing implementation for your containers." Once Docker restarts, you should be able to -successfully run `vagrant up --provider=docker`. Back in Docker, you can return to using VirtioFS -for better system performance while developing, but you may need to revert to `osxfs (legacy)` -whenever you need to re-provision. -::: - ```{include} setup/vagrant-up.md ``` @@ -295,7 +297,83 @@ normal and is not a problem. ``` -Now you're ready for [Step 4: Developing](#step-4-developing). +::: + +:::{tab-item} macOS +:sync: os-mac + +Change into the zulip directory and tell Vagrant to start the Zulip +development environment with `vagrant up`: + +```console +$ cd zulip +$ vagrant up --provider=docker +``` + +**Important note**: There is a [known upstream issue on +macOS](https://chat.zulip.org/#narrow/stream/21-provision-help/topic/provision.20error.20ERR_PNPM_LINKING_FAILED/near/1649241) +that can cause provisioning to fail with `ERR_PNPM_LINKING_FAILED` or +other errors. The temporary fix is to open the Docker desktop app's +settings panel, and choose `osxfs (legacy)` under "Choose file sharing +implementation for your containers." Once Docker restarts, you should +be able to successfully run `vagrant up --provider=docker`. Back in +Docker, you can return to using VirtioFS for better system performance +while developing, but you may need to revert to `osxfs (legacy)` +whenever you need to re-provision. + +```{include} setup/vagrant-up.md + +``` + +```{include} setup/vagrant-ssh.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +Change into the zulip directory and tell Vagrant to start the Zulip +development environment with `vagrant up`: + +```console +$ cd zulip +$ vagrant up --provider=docker +``` + +```{include} setup/vagrant-up.md + +``` + +```{include} setup/vagrant-ssh.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +Change into the zulip directory and tell Vagrant to start the Zulip +development environment with `vagrant up`: + +```console +$ cd zulip +$ vagrant up --provider=docker +``` + +```{include} setup/vagrant-up.md + +``` + +```{include} setup/vagrant-ssh.md + +``` + +::: + +:::: ### Step 4: Developing @@ -318,6 +396,63 @@ run `tools/lint` often to make sure you're following our coding style (or use `tools/setup-git-repo` to run it on just the changed files automatically whenever you commit). +#### VSCode setup (optional) + +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + +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: + +```console +$ code . +``` + +to open VS Code connected to your WSL environment. See the [Remote development in WSL][remote-wsl] tutorial for more information. +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + +```{include} setup/vscode-vagrant.md + +``` + +::: + +:::{tab-item} macOS +:sync: os-mac + +```{include} setup/vscode-vagrant.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +```{include} setup/vscode-vagrant.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +```{include} setup/vscode-vagrant.md + +``` + +::: + +:::: + #### Understanding run-dev debugging output It's good to have the terminal running `./tools/run-dev` up as you work since error @@ -338,28 +473,221 @@ guide][rtd-git-guide]. #### Maintaining the development environment +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + +If after rebasing onto a new version of the Zulip server, you receive +new errors while starting the Zulip server or running tests, this is +probably not because Zulip's `main` branch is broken. Instead, this +is likely because we've recently merged changes to the development +environment provisioning process that you need to apply to your +development environment. To update your environment, you'll need to +re-provision using `tools/provision` from your Zulip checkout; this +should complete in about a minute. + +After provisioning, you'll want to +[(re)start the Zulip development server](/development/setup-recommended.md#step-3-start-the-development-environment). + +If you run into any trouble, [#provision +help](https://chat.zulip.org/#narrow/stream/21-provision-help) in the +[Zulip development community +server](https://zulip.com/development-community/) is a great place to ask for +help. + +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + ```{include} setup/vagrant-update.md ``` +::: + +:::{tab-item} macOS +:sync: os-mac + +```{include} setup/vagrant-update.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +```{include} setup/vagrant-update.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +```{include} setup/vagrant-update.md + +``` + +::: + +:::: + #### Rebuilding the development environment +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + ```{include} setup/vagrant-rebuild.md ``` +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + +```{include} setup/vagrant-rebuild.md + +``` + +::: + +:::{tab-item} macOS +:sync: os-mac + +```{include} setup/vagrant-rebuild.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +```{include} setup/vagrant-rebuild.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +```{include} setup/vagrant-rebuild.md + +``` + +::: + +:::: + #### Shutting down the development environment for use later +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + +On Windows with WSL 2, you do not need to shut down the environment. Simply +close your terminal window(s). +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + ```{include} setup/vagrant-halt.md ``` +::: + +:::{tab-item} macOS +:sync: os-mac + +```{include} setup/vagrant-halt.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +```{include} setup/vagrant-halt.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +```{include} setup/vagrant-halt.md + +``` + +::: + +:::: + #### Resuming the development environment +::::{tab-set} + +:::{tab-item} Windows (WSL) +:sync: os-windows + +On Windows with WSL 2, to resume developing you just need to open a new Git +BASH window. Then change into your `zulip` folder and verify the Python +environment was properly activated (you will see `(zulip-py3-venv)`). If the +`(zulip-py3-venv)` part is missing, run +`source /srv/zulip-py3-venv/bin/activate`. +::: + +:::{tab-item} Windows (VM) +:sync: os-windows-vm + ```{include} setup/vagrant-resume.md ``` +::: + +:::{tab-item} macOS +:sync: os-mac + +```{include} setup/vagrant-resume.md + +``` + +::: + +:::{tab-item} Ubuntu/Debian +:sync: os-ubuntu + +```{include} setup/vagrant-resume.md + +``` + +::: + +:::{tab-item} Fedora +:sync: os-fedora + +```{include} setup/vagrant-resume.md + +``` + +::: + +:::: + ### Next steps Next, read the following to learn more about developing for Zulip: @@ -853,6 +1181,8 @@ remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from [vagrant-dl]: https://www.vagrantup.com/downloads.html [install-advanced]: setup-advanced.md +[remote-wsl]: https://code.visualstudio.com/docs/remote/wsl-tutorial +[remote-ssh]: https://code.visualstudio.com/docs/remote/ssh-tutorial [rtd-git-guide]: ../git/index.md [rtd-testing]: ../testing/testing.md [rtd-using-dev-env]: using.md diff --git a/docs/development/setup/vagrant-up.md b/docs/development/setup/vagrant-up.md index a3c770d186..e326b7dffe 100644 --- a/docs/development/setup/vagrant-up.md +++ b/docs/development/setup/vagrant-up.md @@ -1,8 +1,7 @@ The first time you run this command it will take some time because Vagrant does the following: -- downloads the base Ubuntu 20.04 virtual machine image (for macOS and Windows) - or container (for Linux) +- downloads the base Ubuntu 20.04 virtual machine/Docker image - configures this virtual machine/container for use with Zulip, - creates a shared directory mapping your clone of the Zulip code inside the virtual machine/container at `~/zulip` diff --git a/docs/development/setup/vscode-vagrant.md b/docs/development/setup/vscode-vagrant.md new file mode 100644 index 0000000000..384ed93894 --- /dev/null +++ b/docs/development/setup/vscode-vagrant.md @@ -0,0 +1,34 @@ +If your preferred editor is Virtual Studio Code, the [Visual Studio +Code Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) +extension is recommended for editing files when developing with +Vagrant. When you have it installed, you can run: + +```console +$ code . +``` + +to open VS Code connected to your Vagrant environment. See the +[Remote development over SSH][remote-ssh] tutorial for more information. + +When using this plugin with Vagrant, you will want to run the command +`vagrant ssh-config` from your `zulip` folder: + +```console +$ vagrant ssh-config +Host default + HostName 127.0.0.1 + User vagrant + Port 2222 + UserKnownHostsFile /dev/null + StrictHostKeyChecking no + PasswordAuthentication no + IdentityFile /PATH/TO/zulip/.vagrant/machines/default/docker/private_key + IdentitiesOnly yes + LogLevel FATAL + PubkeyAcceptedKeyTypes +ssh-rsa + HostKeyAlgorithms +ssh-rsa +``` + +Then copy that config into your `~/.ssh/config` file. You may want to change +the host name from `default` to something more descriptive, like `zulip`. +Finally, refresh the known remotes in Visual Studio Code's Remote Explorer. diff --git a/docs/git/cloning.md b/docs/git/cloning.md index cd24c01968..2458abb178 100644 --- a/docs/git/cloning.md +++ b/docs/git/cloning.md @@ -99,9 +99,6 @@ 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 or 11, -you are ready to [continue with step 9](../development/setup-recommended.md#windows-10-or-11). - ## Step 3: Configure continuous integration for your fork This step is optional, but recommended.