Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/docs/development/overview.md

85 lines
3.3 KiB
Markdown
Raw Normal View History

dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
# Development environment installation
Move development installations instructions to a separate file. This will make the core README.md file cleaner.
2015-11-04 05:57:54 +01:00
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Requirements
dev-overview: Document cloud server option.
2016-10-11 02:10:39 +02:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
The Zulip development environment can be installed on **macOS,
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
Windows, and Linux** (Debian or Ubuntu recommended). You'll need at least **2GB
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
of available RAM**.
dev-overview: Document cloud server option.
2016-10-11 02:10:39 +02:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
Installing the Zulip development environment requires downloading several hundred
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
megabytes of dependencies, so you will need an **active, reasonably fast,
internet connection throughout the entire installation processes.** You can
[configure a proxy][configure-proxy] if you need one.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Simplify hierarchy of dev setup docs. Based on feedback from first-time contributors, this commit simplifies the number of paths available for finding the dev setup directions you need. Setup instructions are now organized into Recommended (Vagrant) and Advanced (non-Vagrant). In order to get the ToC to display correctly, I've combined all the advanced, non-Vagrant methods into one page. I've left the old pages intact, with a note that the content has been moved and link to the new page. This is in case folks have linked directly to those pages. The advanced setup directions still need to be cleaned up, but this is a start.
2016-11-28 02:50:33 +01:00
## Recommended setup (Vagrant)
Move development installations instructions to a separate file. This will make the core README.md file cleaner.
2015-11-04 05:57:54 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
**For first-time contributors, we recommend using the
[Vagrant development environment][install-vagrant]**.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
This method creates a virtual machine (for Windows and macOS) or a
Linux container (otherwise) inside which the Zulip server and all
related services will run. Vagrant adds a bit of overhead to using the
Zulip development server, but provides an isolated environment that is
easy to install, update, and uninstall. It has been well-tested and
performs well.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Delete manual development installation documentation. This documentation does not work and has not been used for years. At this point, `provision` is sufficiently flexible in terms of supporting different platforms that any future work will be to extend it, rather than maintaining awkward manual installation documentation.
2021-04-14 06:23:26 +02:00
## Advanced setup
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
Zulip also supports a wide range of ways to install the Zulip
development environment:
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Delete manual development installation documentation. This documentation does not work and has not been used for years. At this point, `provision` is sufficiently flexible in terms of supporting different platforms that any future work will be to extend it, rather than maintaining awkward manual installation documentation.
2021-04-14 06:23:26 +02:00
* On Linux platforms, you can **[install directly][install-direct]**.
docs: Identify WSL 2 with normal capitalization.
2021-03-24 01:12:50 +01:00
* On Windows, you can **[install directly][install-via-wsl]** via WSL 2.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Slow internet connections
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
If you have a very slow network connection, however, you may want to
avoid using Vagrant (which involves downloading an Ubuntu virtual
docs: Delete manual development installation documentation. This documentation does not work and has not been used for years. At this point, `provision` is sufficiently flexible in terms of supporting different platforms that any future work will be to extend it, rather than maintaining awkward manual installation documentation.
2021-04-14 06:23:26 +02:00
machine or Linux container) and [install directly][install-direct] on
a Linux system.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
An alternative option if you have poor network connectivity is to rent
a cloud server and install the Zulip development environment for
remote use. See the [next section][self-install-remote] for details.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Installing remotely
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
The Zulip development environment works well on remote virtual
machines. This can be a good alternative for those with poor network
connectivity or who have limited storage/memory on their local
machines.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
We recommend giving the Zulip development environment its **own
virtual machine**, running one of
[the supported platforms for direct installation][install-direct],
with at least **2GB of memory**.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
If the Zulip development environment will be the only thing running on
the remote virtual machine, we recommend installing
[directly][install-direct]. Otherwise, we recommend the
[Vagrant][install-vagrant] method so you can easily uninstall if you
need to.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Next steps
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
Once you've installed the Zulip development environment, you'll want
to read these documents to learn how to use it:
docs: Fix more capitalization issues. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-10-23 02:43:28 +02:00
* [Using the development environment][using-dev-env]
docs: Update docs/git/ directory to reflect CI changes. This isn't complete, in that we still need to rename the ReadTheDocs articles (e.g.).
2018-12-10 17:12:58 +01:00
* [Testing][testing] (and [Configuring CI][ci])
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Correct “setup” as a verb to “set up”. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-08-11 01:47:54 +02:00
And if you've set up the Zulip development environment on a remote
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
machine, take a look at our tips for
[developing remotely][dev-remote].
Improve first-time contributor docs. Fixes #747. Fixes #748. This updates README.dev.md to include clear, step-by-step instructions for setting up the Zulip dev environment Windows 10, OS X El Capitan, Ubuntu 14.04 Trusty, and Ubuntu 16.04 Xenial. It is aimed at first-time contributors. I tested these instructions multiple times on each of the target systems. Also added is a "trobleshooting and common errors" section which documents the most common errors contributors are likely to encounter during setup and how to fix them. Improvements based on feedback from @timabbott. - Fixes whitespace issues so linter will pass. - Updates memory requirement. - Re-orders so operating systems are listed alphabetically. - Updates headings to be clearer. - Updates and adds ToC entries for clarity. - Adds screen shot of Zulip dev environment running in browser. - Adds details about using dev environment, including about logging. - Misc other minor changes for clarity. - Adds a stub for docs/logging.md - Adds details about configuring Cygwin for native symlinks.
2016-05-05 01:16:31 +02:00
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[dev-remote]: remote.md
Revert "docs: Update .html links to .md." This doesn't work without the CommonMark upgrade. This reverts commit c87893feeacaa78315ffc72510afe8e92477f4e8.
2019-04-06 02:58:44 +02:00
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[install-vagrant]: ../development/setup-vagrant.md
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
[self-install-remote]: #installing-remotely
[self-slow-internet]: #slow-internet-connections
Revert "docs: Update .html links to .md." This doesn't work without the CommonMark upgrade. This reverts commit c87893feeacaa78315ffc72510afe8e92477f4e8.
2019-04-06 02:58:44 +02:00
[configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[using-dev-env]: using.md
[testing]: ../testing/testing.md
Revert "docs: Update .html links to .md." This doesn't work without the CommonMark upgrade. This reverts commit c87893feeacaa78315ffc72510afe8e92477f4e8.
2019-04-06 02:58:44 +02:00
[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork
docs: Update recommendations of Windows installation methods. This change attempts to highlight WSL 2 as the default installation method for Windows; that is currently much more reliable than Vagrant. Further work is probably needed to complete this transition.
2021-04-14 06:29:13 +02:00
[install-via-wsl]: ../development/setup-advanced.html#installing-directly-on-windows-10-with-wsl-2