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

docs: Clean redundant relative links. 

We previously had a convention of redundantly including the directory
in relative links to reduce mistakes when moving content from one file
to another.  However, these days we have a broken link checker in
test-documentation, and after #21237, MyST-Parser will check relative
links (including fragments) when you run build-docs.

Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
Anders Kaseorg 2022-02-23 15:17:21 -08:00 committed by Anders Kaseorg
parent e3572894c5
commit c19d6fb3ef
62 changed files with 186 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/contributing/code-reviewing.md
View File

@ -236,8 +236,8 @@ We also strongly recommend reviewers to go through the following resources.
article by James J. Porter article by James J. Porter
- [Zulip code of conduct](../code-of-conduct.md) - [Zulip code of conduct](../code-of-conduct.md)
[code-style]: ../contributing/code-style.md [code-style]: code-style.md
[commit-messages]: ../contributing/version-control.html#commit-messages [commit-messages]: version-control.html#commit-messages
[test-writing]: ../testing/testing.md [test-writing]: ../testing/testing.md
[mypy]: ../testing/mypy.md [mypy]: ../testing/mypy.md
[git tool]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase [git tool]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase

2
docs/contributing/gsoc.md
View File

@ -54,7 +54,7 @@ maintainers.
To learn more about the experience of doing GSoC with Zulip, check out our To learn more about the experience of doing GSoC with Zulip, check out our
[Zulip's Google Summer of Code 2021 blog [Zulip's Google Summer of Code 2021 blog
post](https://blog.zulip.com/2021/09/30/google-summer-of-code-2021/). Our [guide post](https://blog.zulip.com/2021/09/30/google-summer-of-code-2021/). Our [guide
for having a great summer with Zulip](../contributing/summer-with-zulip.md) will for having a great summer with Zulip](summer-with-zulip.md) will
also give you a feel for what it's like to do GSoC with us. also give you a feel for what it's like to do GSoC with us.
> _“It has been the best summer I've ever had! I'm thankful to my mentors, my > _“It has been the best summer I've ever had! I'm thankful to my mentors, my

4
docs/development/authentication.md
View File

@ -138,9 +138,9 @@ details worth understanding:
Some OAuth providers (such as Facebook) require HTTPS on the callback Some OAuth providers (such as Facebook) require HTTPS on the callback
URL they post back to, which isn't supported directly by the Zulip URL they post back to, which isn't supported directly by the Zulip
development environment. If you run a development environment. If you run a
[remote Zulip development server](../development/remote.md), we have [remote Zulip development server](remote.md), we have
instructions for instructions for
[an nginx reverse proxy with SSL](../development/remote.html#using-an-nginx-reverse-proxy) [an nginx reverse proxy with SSL](remote.html#using-an-nginx-reverse-proxy)
that you can use for your development efforts. that you can use for your development efforts.
## Testing LDAP in development ## Testing LDAP in development

8
docs/development/overview.md
View File

@ -76,12 +76,12 @@ machine, take a look at our tips for
[developing remotely][dev-remote]. [developing remotely][dev-remote].
[dev-remote]: remote.md [dev-remote]: remote.md
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora [install-direct]: setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora
[install-vagrant]: ../development/setup-vagrant.md [install-vagrant]: setup-vagrant.md
[self-install-remote]: #installing-remotely [self-install-remote]: #installing-remotely
[self-slow-internet]: #slow-internet-connections [self-slow-internet]: #slow-internet-connections
[configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy [configure-proxy]: setup-vagrant.html#specifying-a-proxy
[using-dev-env]: using.md [using-dev-env]: using.md
[testing]: ../testing/testing.md [testing]: ../testing/testing.md
[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork [ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork
[install-via-wsl]: ../development/setup-advanced.html#installing-directly-on-windows-10-with-wsl-2 [install-via-wsl]: setup-advanced.html#installing-directly-on-windows-10-with-wsl-2

4
docs/development/remote.md
View File

@ -270,8 +270,8 @@ Next, read the following to learn more about developing for Zulip:
- [Using the development environment][rtd-using-dev-env] - [Using the development environment][rtd-using-dev-env]
- [Testing][rtd-testing] - [Testing][rtd-testing]
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora [install-direct]: setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora
[install-vagrant]: ../development/setup-vagrant.md [install-vagrant]: setup-vagrant.md
[rtd-git-guide]: ../git/index.md [rtd-git-guide]: ../git/index.md
[rtd-using-dev-env]: using.md [rtd-using-dev-env]: using.md
[rtd-testing]: ../testing/testing.md [rtd-testing]: ../testing/testing.md

4
docs/development/request-remote.md
View File

@ -70,13 +70,13 @@ Once your remote dev instance is ready:
Once you've confirmed you can connect to your remote server, take a look at: Once you've confirmed you can connect to your remote server, take a look at:
- [developing remotely](../development/remote.md) for tips on using the remote dev - [developing remotely](remote.md) for tips on using the remote dev
instance, and instance, and
- our [Git & GitHub guide](../git/index.md) to learn how to use Git with Zulip. - our [Git & GitHub guide](../git/index.md) to learn how to use Git with Zulip.
Next, read the following to learn more about developing for Zulip: Next, read the following to learn more about developing for Zulip:
- [Using the development environment](../development/using.md) - [Using the development environment](using.md)
- [Testing](../testing/testing.md) - [Testing](../testing/testing.md)
[github-join]: https://github.com/join [github-join]: https://github.com/join

8
docs/development/setup-advanced.md
View File

@ -21,9 +21,9 @@ that's running one of:
You can just run the Zulip provision script on your machine. You can just run the Zulip provision script on your machine.
**Note**: You should not use the `root` user to run the installation. **Note**: You should not use the `root` user to run the installation.
If you are using a [remote server](../development/remote.md), see If you are using a [remote server](remote.md), see
the the
[section on creating appropriate user accounts](../development/remote.html#setting-up-user-accounts). [section on creating appropriate user accounts](remote.html#setting-up-user-accounts).
:::{warning} :::{warning}
There is no supported uninstallation process with this There is no supported uninstallation process with this
@ -50,7 +50,7 @@ source /srv/zulip-py3-venv/bin/activate
Once you've done the above setup, you can pick up the [documentation Once you've done the above setup, you can pick up the [documentation
on using the Zulip development on using the Zulip development
environment](../development/setup-vagrant.html#step-4-developing), environment](setup-vagrant.html#step-4-developing),
ignoring the parts about `vagrant` (since you're not using it). ignoring the parts about `vagrant` (since you're not using it).
## Installing directly on Windows 10 with WSL 2 ## Installing directly on Windows 10 with WSL 2
@ -151,7 +151,7 @@ installation method described here.
to open VSCode connected to your WSL environment. to open VSCode connected to your WSL environment.
1. You're done! You can pick up the [documentation on using the 1. You're done! You can pick up the [documentation on using the
Zulip development environment](../development/setup-vagrant.html#step-4-developing), Zulip development environment](setup-vagrant.html#step-4-developing),
ignoring the parts about `vagrant` (since you're not using it). ignoring the parts about `vagrant` (since you're not using it).
WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl] WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]

4
docs/development/setup-vagrant.md
View File

@ -151,7 +151,7 @@ Debian](https://docs.docker.com/install/linux/docker-ce/debian/).
#### Windows 10 #### Windows 10
:::{note} :::{note}
We recommend using [WSL 2 for Windows development](../development/setup-advanced.html#installing-directly-on-windows-10-with-wsl-2). We recommend using [WSL 2 for Windows development](setup-advanced.html#installing-directly-on-windows-10-with-wsl-2).
::: :::
1. Install [Git for Windows][git-bash], which installs _Git BASH_. 1. Install [Git for Windows][git-bash], which installs _Git BASH_.
@ -1041,7 +1041,7 @@ remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from
[cygwin-dl]: https://cygwin.com/ [cygwin-dl]: https://cygwin.com/
[vagrant-dl]: https://www.vagrantup.com/downloads.html [vagrant-dl]: https://www.vagrantup.com/downloads.html
[vbox-dl]: https://www.virtualbox.org/wiki/Downloads [vbox-dl]: https://www.virtualbox.org/wiki/Downloads
[install-advanced]: ../development/setup-advanced.md [install-advanced]: setup-advanced.md
[rtd-git-guide]: ../git/index.md [rtd-git-guide]: ../git/index.md
[rtd-testing]: ../testing/testing.md [rtd-testing]: ../testing/testing.md
[rtd-using-dev-env]: using.md [rtd-using-dev-env]: using.md

2
docs/development/using.md
View File

@ -93,7 +93,7 @@ See the mobile project's documentation on [using a development server
for mobile development][mobile-dev-server]. for mobile development][mobile-dev-server].
[rest-api]: https://zulip.com/api/rest [rest-api]: https://zulip.com/api/rest
[authentication-dev-server]: ./authentication.md [authentication-dev-server]: authentication.md
[django-runserver]: https://docs.djangoproject.com/en/3.2/ref/django-admin/#runserver [django-runserver]: https://docs.djangoproject.com/en/3.2/ref/django-admin/#runserver
[new-feature-tutorial]: ../tutorials/new-feature-tutorial.md [new-feature-tutorial]: ../tutorials/new-feature-tutorial.md
[testing-docs]: ../testing/testing.md [testing-docs]: ../testing/testing.md

6
docs/documentation/api.md
View File

@ -27,10 +27,10 @@ the validation Zulip has today.
Our API documentation is defined by a few sets of files: Our API documentation is defined by a few sets of files:
- The primary source of our API documentation is the Zulip server's - The primary source of our API documentation is the Zulip server's
[OpenAPI description](../documentation/openapi.md) at [OpenAPI description](openapi.md) at
`zerver/openapi/zulip.yaml`. `zerver/openapi/zulip.yaml`.
- The documentation is written the same Markdown framework that powers - The documentation is written the same Markdown framework that powers
our [help center docs](../documentation/helpcenter.md), with some special our [help center docs](helpcenter.md), with some special
extensions for rendering nice code blocks and example extensions for rendering nice code blocks and example
responses. Most API endpoints share a common template, responses. Most API endpoints share a common template,
`templates/zerver/api/api-doc-template.md`, which renders the `templates/zerver/api/api-doc-template.md`, which renders the
@ -218,7 +218,7 @@ This section offers a step-by-step process for adding documentation
for a new API endpoint. It assumes you've read and understood the for a new API endpoint. It assumes you've read and understood the
above. above.
1. Start by adding [OpenAPI format](../documentation/openapi.md) 1. Start by adding [OpenAPI format](openapi.md)
data to `zerver/openapi/zulip.yaml` for the endpoint. If you data to `zerver/openapi/zulip.yaml` for the endpoint. If you
copy-paste (which is helpful to get the indentation structure copy-paste (which is helpful to get the indentation structure
right), be sure to update all the content that you copied to right), be sure to update all the content that you copied to

2
docs/documentation/openapi.md
View File

@ -10,7 +10,7 @@ for that file to fully describe every endpoint in the Zulip API, and
for the Zulip test suite to fail should the API every change without a for the Zulip test suite to fail should the API every change without a
corresponding adjustment to the documentation. In particular, corresponding adjustment to the documentation. In particular,
essentially all content in Zulip's [REST API essentially all content in Zulip's [REST API
documentation](../documentation/api.md) is generated from our OpenAPI documentation](api.md) is generated from our OpenAPI
file. file.
In an OpenAPI Swagger file, every configuration section is an object. In an OpenAPI Swagger file, every configuration section is an object.

2
docs/documentation/overview.md
View File

@ -124,7 +124,7 @@ with Zulip. This documentation also serves as our main mechanism for
Zulip server developers to communicate with client developers about Zulip server developers to communicate with client developers about
how the Zulip API works. how the Zulip API works.
See the [API documentation tutorial](../documentation/api.md) for See the [API documentation tutorial](api.md) for
details on how to contribute to this documentation. details on how to contribute to this documentation.
## Automated testing ## Automated testing

2
docs/git/cheat-sheet.md
View File

@ -113,4 +113,4 @@ See also [fixing commits][fix-commit]
[fix-commit]: fixing-commits.md [fix-commit]: fixing-commits.md
[git-config-clone]: cloning.html#step-1b-clone-to-your-machine [git-config-clone]: cloning.html#step-1b-clone-to-your-machine
[git-overview]: ./overview.md [git-overview]: overview.md

2
docs/git/cloning.md
View File

@ -137,4 +137,4 @@ You can check the `Actions` tab of your repository to see the builds.
[github-actions]: https://docs.github.com/en/actions [github-actions]: https://docs.github.com/en/actions
[zulip-rtd-dev-first-time]: ../development/setup-vagrant.md [zulip-rtd-dev-first-time]: ../development/setup-vagrant.md
[zulip-rtd-dev-overview]: ../development/overview.md [zulip-rtd-dev-overview]: ../development/overview.md
[zulip-rtd-tools-setup]: ../git/zulip-tools.html#set-up-git-repo-script [zulip-rtd-tools-setup]: zulip-tools.html#set-up-git-repo-script

2
docs/git/collaborate.md
View File

@ -56,4 +56,4 @@ tools/fetch-pull-request <PR-number>
``` ```
[github-help-co-pr-locally]: https://help.github.com/en/articles/checking-out-pull-requests-locally [github-help-co-pr-locally]: https://help.github.com/en/articles/checking-out-pull-requests-locally
[tools-pr]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase [tools-pr]: zulip-tools.html#fetch-a-pull-request-and-rebase

4
docs/git/overview.md
View File

@ -59,7 +59,7 @@ Git workflow, or if you'd like a Git refresher.
[github-zulip]: https://github.com/zulip/ [github-zulip]: https://github.com/zulip/
[github-zulip-zulip]: https://github.com/zulip/zulip/ [github-zulip-zulip]: https://github.com/zulip/zulip/
[continuous-integration]: ../testing/continuous-integration.md [continuous-integration]: ../testing/continuous-integration.md
[zulip-git-guide-fork-ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork [zulip-git-guide-fork-ci]: cloning.html#step-3-configure-continuous-integration-for-your-fork
[zulip-rtd-code-style]: ../contributing/code-style.md [zulip-rtd-code-style]: ../contributing/code-style.md
[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline [zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages [zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages
@ -67,5 +67,5 @@ Git workflow, or if you'd like a Git refresher.
[zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools [zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools
[zulip-rtd-mypy]: ../testing/mypy.md [zulip-rtd-mypy]: ../testing/mypy.md
[zulip-rtd-testing]: ../testing/testing.md [zulip-rtd-testing]: ../testing/testing.md
[zulip-rtd-zulip-tools]: ../git/zulip-tools.md [zulip-rtd-zulip-tools]: zulip-tools.md
[zulip-rtd-zulipbot-usage]: ../contributing/zulipbot-usage.md [zulip-rtd-zulipbot-usage]: ../contributing/zulipbot-usage.md

4
docs/git/pull-requests.md
View File

@ -158,7 +158,7 @@ for another review.
[github-help-about-pr]: https://help.github.com/en/articles/about-pull-requests [github-help-about-pr]: https://help.github.com/en/articles/about-pull-requests
[github-help-create-pr-fork]: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork [github-help-create-pr-fork]: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork
[images-create-pr]: ../images/zulip-open-pr.png [images-create-pr]: ../images/zulip-open-pr.png
[keep-up-to-date]: ../git/using.html#keep-your-fork-up-to-date [keep-up-to-date]: using.html#keep-your-fork-up-to-date
[self-push-commits]: ../git/using.html#push-your-commits-to-github [self-push-commits]: using.html#push-your-commits-to-github
[screenshots-gifs]: ../tutorials/screenshot-and-gif-software.md [screenshots-gifs]: ../tutorials/screenshot-and-gif-software.md
[wip-prs]: #work-in-progress-pull-requests [wip-prs]: #work-in-progress-pull-requests

4
docs/git/troubleshooting.md
View File

@ -275,8 +275,8 @@ keep,** you'll need to use `git log FETCH_HEAD` to identify that hashes of the
commits you want to keep and then `git cherry-pick <commit>` those commits into commits you want to keep and then `git cherry-pick <commit>` those commits into
whichever branch you need to update. whichever branch you need to update.
[clone-to-your-machine]: ../git/cloning.html#step-1b-clone-to-your-machine [clone-to-your-machine]: cloning.html#step-1b-clone-to-your-machine
[connect-upstream]: ../git/cloning.html#step-1c-connect-your-fork-to-zulip-upstream [connect-upstream]: cloning.html#step-1c-connect-your-fork-to-zulip-upstream
[gitbook-advanced-merging]: https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_advanced_merging [gitbook-advanced-merging]: https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_advanced_merging
[gitbook-basic-merge-conflicts]: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts [gitbook-basic-merge-conflicts]: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts
[gitbook-git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick [gitbook-git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick

4
docs/git/using.md
View File

@ -450,8 +450,8 @@ complicated rebase.
[github-help-push]: https://help.github.com/en/articles/pushing-to-a-remote [github-help-push]: https://help.github.com/en/articles/pushing-to-a-remote
[github-help-rebase]: https://help.github.com/en/articles/using-git-rebase [github-help-rebase]: https://help.github.com/en/articles/using-git-rebase
[github-help-sync-fork]: https://help.github.com/en/articles/syncing-a-fork [github-help-sync-fork]: https://help.github.com/en/articles/syncing-a-fork
[how-git-is-different]: ./the-git-difference.md [how-git-is-different]: the-git-difference.md
[self-multiple-computers]: ../git/troubleshooting.html#working-from-multiple-computers [self-multiple-computers]: troubleshooting.html#working-from-multiple-computers
[zulip-git-guide-up-to-date]: #keep-your-fork-up-to-date [zulip-git-guide-up-to-date]: #keep-your-fork-up-to-date
[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline [zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages [zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages

4
docs/git/working-copies.md
View File

@ -7,7 +7,7 @@ repository that you are generally concerned with:
repository](https://github.com/zulip/zulip) on GitHub. You probably repository](https://github.com/zulip/zulip) on GitHub. You probably
don't have write access to this repository. don't have write access to this repository.
- The **origin** remote: Your personal remote repository on GitHub. - The **origin** remote: Your personal remote repository on GitHub.
You'll use this to share your code and create [pull requests](../git/pull-requests.md). You'll use this to share your code and create [pull requests](pull-requests.md).
- local copy: This lives on your laptop or your remote dev instance, - local copy: This lives on your laptop or your remote dev instance,
and is what you'll use to make changes and create commits. and is what you'll use to make changes and create commits.
@ -45,6 +45,6 @@ working copies:
- `git remote`: This helps you configure short names for remotes. - `git remote`: This helps you configure short names for remotes.
- `git pull`: This pulls code, but by default creates a merge commit - `git pull`: This pulls code, but by default creates a merge commit
(which you definitely don't want). However, if you've followed our (which you definitely don't want). However, if you've followed our
[cloning documentation](../git/cloning.md), this will do [cloning documentation](cloning.md), this will do
`git pull --rebase` instead, which is the only mode you'll want to `git pull --rebase` instead, which is the only mode you'll want to
use when working on Zulip. use when working on Zulip.

4
docs/git/zulip-tools.md
View File

@ -176,5 +176,5 @@ git rebase --continue
``` ```
[github-zulip-zulip]: https://github.com/zulip/zulip/ [github-zulip-zulip]: https://github.com/zulip/zulip/
[zulip-git-guide-fetch-pr]: ../git/collaborate.html#check-out-a-pull-request-locally [zulip-git-guide-fetch-pr]: collaborate.html#check-out-a-pull-request-locally
[zulip-git-guide-ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork [zulip-git-guide-ci]: cloning.html#step-3-configure-continuous-integration-for-your-fork

4
docs/overview/architecture-overview.md
View File

@ -7,7 +7,7 @@ contains the Zulip backend (written in Python 3.x and Django), the
web app (written in JavaScript and TypeScript) and our library of web app (written in JavaScript and TypeScript) and our library of
incoming webhook [integrations](https://zulip.com/integrations) incoming webhook [integrations](https://zulip.com/integrations)
with other services and applications (see [the directory structure with other services and applications (see [the directory structure
guide](../overview/directory-structure.md)). guide](directory-structure.md)).
[Zulip Mobile](https://github.com/zulip/zulip-mobile) is the official [Zulip Mobile](https://github.com/zulip/zulip-mobile) is the official
mobile Zulip client supporting both iOS and Android, written in mobile Zulip client supporting both iOS and Android, written in
@ -109,7 +109,7 @@ feed.
For more details on the frontend, see our documentation on For more details on the frontend, see our documentation on
[translation](../translating/translating.md), [translation](../translating/translating.md),
[templates](../subsystems/html-css.html#html-templates), [templates](../subsystems/html-css.html#html-templates),
[directory structure](../overview/directory-structure.md), and [directory structure](directory-structure.md), and
[the static asset pipeline](../subsystems/html-css.html#static-asset-pipeline). [the static asset pipeline](../subsystems/html-css.html#static-asset-pipeline).
[jinja2]: http://jinja.pocoo.org/ [jinja2]: http://jinja.pocoo.org/

4
docs/overview/changelog.md
View File

@ -1,7 +1,7 @@
# Version history # Version history
This page the release history for the Zulip server. See also the This page the release history for the Zulip server. See also the
[Zulip release lifecycle](../overview/release-lifecycle.md). [Zulip release lifecycle](release-lifecycle.md).
## Zulip 5.x series ## Zulip 5.x series
@ -402,7 +402,7 @@ log][commit-log] for an up-to-date list of raw changes.
#### Full feature changelog #### Full feature changelog
- Added new [release lifecycle documentation](../overview/release-lifecycle.md). - Added new [release lifecycle documentation](release-lifecycle.md).
- Added support for subscribing another stream's membership to a stream. - Added support for subscribing another stream's membership to a stream.
- Added RealmAuditLog for most settings state changes in Zulip; this - Added RealmAuditLog for most settings state changes in Zulip; this
data will facilitate future features showing a log of activity by data will facilitate future features showing a log of activity by

8
docs/production/authentication-methods.md
View File

@ -384,7 +384,7 @@ it as follows:
the "SAML ACS url" in SAML terminology. the "SAML ACS url" in SAML terminology.
If you're If you're
[hosting multiple organizations](../production/multiple-organizations.html#authentication), [hosting multiple organizations](multiple-organizations.html#authentication),
you need to use `SOCIAL_AUTH_SUBDOMAIN`. For example, you need to use `SOCIAL_AUTH_SUBDOMAIN`. For example,
if `SOCIAL_AUTH_SUBDOMAIN="auth"` and `EXTERNAL_HOST=zulip.example.com`, if `SOCIAL_AUTH_SUBDOMAIN="auth"` and `EXTERNAL_HOST=zulip.example.com`,
this should be `https://auth.zulip.example.com/complete/saml/`. this should be `https://auth.zulip.example.com/complete/saml/`.
@ -478,7 +478,7 @@ it as follows:
profile fields during login, not during account creation; we profile fields during login, not during account creation; we
consider this [a bug](https://github.com/zulip/zulip/issues/18746). consider this [a bug](https://github.com/zulip/zulip/issues/18746).
1. [Restart the Zulip server](../production/settings.md) to ensure 1. [Restart the Zulip server](settings.md) to ensure
your settings changes take effect. The Zulip login page should now your settings changes take effect. The Zulip login page should now
have a button for SAML authentication that you can use to log in or have a button for SAML authentication that you can use to log in or
create an account (including when creating a new organization). create an account (including when creating a new organization).
@ -817,7 +817,7 @@ self-hosted servers. To do so, you'll need to do the following:
[apple-developer]: https://developer.apple.com/account/resources/ [apple-developer]: https://developer.apple.com/account/resources/
[apple-create-private-key]: https://help.apple.com/developer-account/?lang=en#/dev77c875b7e [apple-create-private-key]: https://help.apple.com/developer-account/?lang=en#/dev77c875b7e
[apple-get-started]: https://developer.apple.com/sign-in-with-apple/get-started/ [apple-get-started]: https://developer.apple.com/sign-in-with-apple/get-started/
[outgoing-email]: ../production/email.md [outgoing-email]: email.md
## OpenID Connect ## OpenID Connect
@ -876,4 +876,4 @@ passwordless login as any user in a development environment. It's
mentioned on this page only for completeness. mentioned on this page only for completeness.
[custom-profile-fields]: https://zulip.com/help/add-custom-profile-fields [custom-profile-fields]: https://zulip.com/help/add-custom-profile-fields
[update-inline-comments]: ../production/upgrade-or-modify.html#updating-settings-py-inline-documentation [update-inline-comments]: upgrade-or-modify.html#updating-settings-py-inline-documentation

30
docs/production/deployment.md
View File

@ -18,8 +18,8 @@ git clone https://github.com/zulip/zulip.git zulip-server-git
``` ```
and then and then
[continue the normal installation instructions](../production/install.html#step-2-install-zulip). [continue the normal installation instructions](install.html#step-2-install-zulip).
You can also [upgrade Zulip from Git](../production/upgrade-or-modify.html#upgrading-from-a-git-repository). You can also [upgrade Zulip from Git](upgrade-or-modify.html#upgrading-from-a-git-repository).
The most common use case for this is upgrading to `main` to get a The most common use case for this is upgrading to `main` to get a
feature that hasn't made it into an official release yet (often feature that hasn't made it into an official release yet (often
@ -33,14 +33,14 @@ In particular, we are always very glad to investigate problems with
installing Zulip from `main`; they are rare and help us ensure that installing Zulip from `main`; they are rare and help us ensure that
our next major release has a reliable install experience. our next major release has a reliable install experience.
[upgrade-to-main]: ../production/upgrade-or-modify.html#upgrading-to-main [upgrade-to-main]: upgrade-or-modify.html#upgrading-to-main
[upgrade-to-future-release]: ../production/upgrade-or-modify.html#upgrading-to-future-releases [upgrade-to-future-release]: upgrade-or-modify.html#upgrading-to-future-releases
## Zulip in Docker ## Zulip in Docker
Zulip has an officially supported, experimental Zulip has an officially supported, experimental
[docker image](https://github.com/zulip/docker-zulip). Please note [docker image](https://github.com/zulip/docker-zulip). Please note
that Zulip's [normal installer](../production/install.md) has been that Zulip's [normal installer](install.md) has been
extremely reliable for years, whereas the Docker image is new and has extremely reliable for years, whereas the Docker image is new and has
rough edges, so we recommend the normal installer unless you have a rough edges, so we recommend the normal installer unless you have a
specific reason to prefer Docker. specific reason to prefer Docker.
@ -49,7 +49,7 @@ specific reason to prefer Docker.
The Zulip installer supports the following advanced installer options The Zulip installer supports the following advanced installer options
as well as those mentioned in the as well as those mentioned in the
[install](../production/install.html#installer-options) documentation: [install](install.html#installer-options) documentation:
- `--postgresql-version`: Sets the version of PostgreSQL that will be - `--postgresql-version`: Sets the version of PostgreSQL that will be
installed. We currently support PostgreSQL 10, 11, 12, 13, and 14. installed. We currently support PostgreSQL 10, 11, 12, 13, and 14.
@ -83,7 +83,7 @@ as well as those mentioned in the
Zulip's installation process assumes it is the only application Zulip's installation process assumes it is the only application
running on the server; though installing alongside other applications running on the server; though installing alongside other applications
is not recommended, we do have [some notes on the is not recommended, we do have [some notes on the
process](../production/install-existing-server.md). process](install-existing-server.md).
## Running Zulip's service dependencies on different machines ## Running Zulip's service dependencies on different machines
@ -132,7 +132,7 @@ below.
#### Step 1: Set up Zulip #### Step 1: Set up Zulip
Follow the [standard instructions](../production/install.md), with one Follow the [standard instructions](install.md), with one
change. When running the installer, pass the `--no-init-db` change. When running the installer, pass the `--no-init-db`
flag, e.g.: flag, e.g.:
@ -535,7 +535,7 @@ configuration of `pg_hba.conf` and client certificates on the
replica. replica.
[warm-standby]: https://www.postgresql.org/docs/current/warm-standby.html [warm-standby]: https://www.postgresql.org/docs/current/warm-standby.html
[wal-g]: ../production/export-and-import.html#backup-details [wal-g]: export-and-import.html#backup-details
## System and deployment configuration ## System and deployment configuration
@ -575,7 +575,7 @@ that include:
- **`zulip::profile::rabbitmq`** - **`zulip::profile::rabbitmq`**
If you are using a [Apache as a single-sign-on If you are using a [Apache as a single-sign-on
authenticator](../production/authentication-methods.html#apache-based-sso-with-remote-user), authenticator](authentication-methods.html#apache-based-sso-with-remote-user),
you will need to add **`zulip::apache_sso`** to the list. you will need to add **`zulip::apache_sso`** to the list.
#### `pgroonga` #### `pgroonga`
@ -604,7 +604,7 @@ for servers that are upgraded frequently by core Zulip developers.
#### `git_repo_url` #### `git_repo_url`
Default repository URL used when [upgrading from a Git Default repository URL used when [upgrading from a Git
repository](../production/upgrade-or-modify.html#upgrading-from-a-git-repository). repository](upgrade-or-modify.html#upgrading-from-a-git-repository).
### `[application_server]` ### `[application_server]`
@ -626,7 +626,7 @@ configure `settings.py` and set this to true to configure
`nginx`. Remove this field to return to the local uploads backend (any `nginx`. Remove this field to return to the local uploads backend (any
non-empty value is currently equivalent to true). non-empty value is currently equivalent to true).
[s3-uploads]: ../production/upload-backends.html#s3-backend-configuration [s3-uploads]: upload-backends.html#s3-backend-configuration
#### `queue_workers_multiprocess` #### `queue_workers_multiprocess`
@ -669,7 +669,7 @@ more than 3.5GiB of RAM, 4 on hosts with less.
#### `mailname` #### `mailname`
The hostname that [Postfix should be configured to receive mail The hostname that [Postfix should be configured to receive mail
at](../production/email-gateway.html#local-delivery-setup). at](email-gateway.html#local-delivery-setup).
### `[postgresql]` ### `[postgresql]`
@ -694,7 +694,7 @@ Set to true to enable replication to enable [log shipping replication
between PostgreSQL servers](#postgresql-warm-standby). This should be between PostgreSQL servers](#postgresql-warm-standby). This should be
enabled on the primary, as well as any replicas, and further requires enabled on the primary, as well as any replicas, and further requires
configuration of configuration of
[wal-g](../production/export-and-import.html#backup-details). [wal-g](export-and-import.html#backup-details).
#### `replication_primary` #### `replication_primary`
@ -726,7 +726,7 @@ connections.
#### `version` #### `version`
The version of PostgreSQL that is in use. Do not set by hand; use the The version of PostgreSQL that is in use. Do not set by hand; use the
[PostgreSQL upgrade tool](../production/upgrade-or-modify.html#upgrading-postgresql). [PostgreSQL upgrade tool](upgrade-or-modify.html#upgrading-postgresql).
### `[memcached]` ### `[memcached]`

2
docs/production/email-gateway.md
View File

@ -96,7 +96,7 @@ using an [HTTP reverse proxy][reverse-proxy]).
Congratulations! The integration should be fully operational. Congratulations! The integration should be fully operational.
[reverse-proxy]: ../production/deployment.html#putting-the-zulip-application-behind-a-reverse-proxy [reverse-proxy]: deployment.html#putting-the-zulip-application-behind-a-reverse-proxy
## Polling setup ## Polling setup

24
docs/production/export-and-import.md
View File

@ -48,9 +48,9 @@ service (or back):
decommissioning a Zulip organization. decommissioning a Zulip organization.
- It's possible to set up [PostgreSQL streaming - It's possible to set up [PostgreSQL streaming
replication](../production/deployment.html#postgresql-warm-standby) replication](deployment.html#postgresql-warm-standby)
and the [S3 file upload and the [S3 file upload
backend](../production/upload-backends.html#s3-backend-configuration) backend](upload-backends.html#s3-backend-configuration)
as part of a high availability environment. as part of a high availability environment.
## Backups ## Backups
@ -99,7 +99,7 @@ disrupting service (e.g. `zuliptest.example.com` rather than
`zulip.example.com`). `zulip.example.com`).
If you do so, just like any other time you change the hostname, you'll If you do so, just like any other time you change the hostname, you'll
need to [update `EXTERNAL_HOST`](../production/settings.md) and then need to [update `EXTERNAL_HOST`](settings.md) and then
restart the Zulip server (after backup restoration completes). restart the Zulip server (after backup restoration completes).
Until you do, your Zulip server will think its user-facing hostname is Until you do, your Zulip server will think its user-facing hostname is
@ -118,7 +118,7 @@ extracting the entire archive.
tar -Oaxf /path/to/archive/zulip-backup-rest.tar.gz zulip-backup/zulip-version tar -Oaxf /path/to/archive/zulip-backup-rest.tar.gz zulip-backup/zulip-version
``` ```
[install-server]: ../production/install.md [install-server]: install.md
### What is included ### What is included
@ -134,7 +134,7 @@ and you may want to back up separately:
the rest of the data for a Zulip server. the rest of the data for a Zulip server.
- Files uploaded with the Zulip - Files uploaded with the Zulip
[S3 file upload backend](../production/upload-backends.md). We [S3 file upload backend](upload-backends.md). We
don't include these for two reasons. First, the uploaded file data don't include these for two reasons. First, the uploaded file data
in S3 can easily be many times larger than the rest of the backup, in S3 can easily be many times larger than the rest of the backup,
and downloading it all to a server doing a backup could easily and downloading it all to a server doing a backup could easily
@ -193,7 +193,7 @@ data includes:
filenames are computed using a hash of `avatar_salt` and user's filenames are computed using a hash of `avatar_salt` and user's
email), etc. email), etc.
[export-import]: ../production/export-and-import.md [export-import]: export-and-import.md
### Restore from manual backups ### Restore from manual backups
@ -285,7 +285,7 @@ archive of all the organization's uploaded files.
## Import into a new Zulip server ## Import into a new Zulip server
1. [Install a new Zulip server](../production/install.md), 1. [Install a new Zulip server](install.md),
**skipping Step 3** (you'll create your Zulip organization via the data **skipping Step 3** (you'll create your Zulip organization via the data
import tool instead). import tool instead).
@ -320,7 +320,7 @@ archive of all the organization's uploaded files.
`/etc/zulip/zulip-secrets.conf` (details below). `/etc/zulip/zulip-secrets.conf` (details below).
- If you copy `zulip_org_id` and `zulip_org_key` (the credentials - If you copy `zulip_org_id` and `zulip_org_key` (the credentials
for the [mobile push notifications for the [mobile push notifications
service](../production/mobile-push-notifications.md)), you should service](mobile-push-notifications.md)), you should
be very careful to make sure the no users had their IDs be very careful to make sure the no users had their IDs
renumbered during the import process (this can be checked using renumbered during the import process (this can be checked using
`manage.py shell` with some care). The push notifications `manage.py shell` with some care). The push notifications
@ -365,7 +365,7 @@ cd /home/zulip/deployments/current
This could take several minutes to run depending on how much data you're This could take several minutes to run depending on how much data you're
importing. importing.
[upgrade-zulip-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository [upgrade-zulip-from-git]: upgrade-or-modify.html#upgrading-from-a-git-repository
#### Import options #### Import options
@ -411,10 +411,10 @@ delete the test import data from your Zulip server before doing a
final import. You can **permanently delete** all data from a Zulip final import. You can **permanently delete** all data from a Zulip
organization using the following procedure: organization using the following procedure:
- Start a [Zulip management shell](../production/management-commands.html#manage-py-shell) - Start a [Zulip management shell](management-commands.html#manage-py-shell)
- In the management shell, run the following commands, replacing `""` - In the management shell, run the following commands, replacing `""`
with the subdomain if [you are hosting the organization on a with the subdomain if [you are hosting the organization on a
subdomain](../production/multiple-organizations.md): subdomain](multiple-organizations.md):
```python ```python
realm = Realm.objects.get(string_id="") realm = Realm.objects.get(string_id="")
@ -430,7 +430,7 @@ Now, exit the management shell and run this to clear Zulip's cache:
``` ```
Assuming you're using the Assuming you're using the
[local file uploads backend](../production/upload-backends.md), you [local file uploads backend](upload-backends.md), you
can additionally delete all file uploads, avatars, and custom emoji on can additionally delete all file uploads, avatars, and custom emoji on
a Zulip server (across **all organizations**) with the following a Zulip server (across **all organizations**) with the following
command: command:

20
docs/production/install.md
View File

@ -1,11 +1,11 @@
# Production installation # Production installation
You'll need an Ubuntu or Debian system that satisfies You'll need an Ubuntu or Debian system that satisfies
[the installation requirements](../production/requirements.md). Alternatively, [the installation requirements](requirements.md). Alternatively,
you can use a preconfigured you can use a preconfigured
[DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or [DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or
Zulip's Zulip's
[experimental Docker image](../production/deployment.html#zulip-in-docker). [experimental Docker image](deployment.html#zulip-in-docker).
Note that if you're developing for Zulip, you should install Zulip's Note that if you're developing for Zulip, you should install Zulip's
[development environment](../development/overview.md) instead. If [development environment](../development/overview.md) instead. If
@ -27,7 +27,7 @@ tar -xf zulip-server-latest.tar.gz
- If you'd like to verify the download, we - If you'd like to verify the download, we
[publish the sha256sums of our release tarballs](https://download.zulip.com/server/SHA256SUMS.txt). [publish the sha256sums of our release tarballs](https://download.zulip.com/server/SHA256SUMS.txt).
- You can also - You can also
[install a pre-release version of Zulip](../production/deployment.html#installing-zulip-from-git) [install a pre-release version of Zulip](deployment.html#installing-zulip-from-git)
using code from our [repository on GitHub](https://github.com/zulip/zulip/). using code from our [repository on GitHub](https://github.com/zulip/zulip/).
## Step 2: Install Zulip ## Step 2: Install Zulip
@ -72,10 +72,10 @@ If the script gives an error, consult [Troubleshooting](#troubleshooting) below.
You can see the more advanced installer options in our [deployment options][doc-deployment-options] You can see the more advanced installer options in our [deployment options][doc-deployment-options]
documentation. documentation.
[doc-settings]: ../production/settings.md [doc-settings]: settings.md
[doc-certbot]: ../production/ssl-certificates.html#certbot-recommended [doc-certbot]: ssl-certificates.html#certbot-recommended
[doc-ssl-manual]: ../production/ssl-certificates.html#manual-install [doc-ssl-manual]: ssl-certificates.html#manual-install
[doc-deployment-options]: ../production/deployment.html#advanced-installer-options [doc-deployment-options]: deployment.html#advanced-installer-options
## Step 3: Create a Zulip organization, and log in ## Step 3: Create a Zulip organization, and log in
@ -85,7 +85,7 @@ or another Zulip server, you should stop here
and return to the import instructions. and return to the import instructions.
[slack-import]: https://zulip.com/help/import-from-slack [slack-import]: https://zulip.com/help/import-from-slack
[zulip-backups]: ../production/export-and-import.html#backups [zulip-backups]: export-and-import.html#backups
Otherwise, open the link in a browser. Follow the prompts to set up Otherwise, open the link in a browser. Follow the prompts to set up
your organization, and your own user account as an administrator. your organization, and your own user account as an administrator.
@ -117,8 +117,8 @@ Learning more:
releases](../overview/release-lifecycle.md) and security issues. releases](../overview/release-lifecycle.md) and security issues.
- Follow [Zulip on Twitter](https://twitter.com/zulip). - Follow [Zulip on Twitter](https://twitter.com/zulip).
- Learn how to [configure your Zulip server settings](settings.md). - Learn how to [configure your Zulip server settings](settings.md).
- Learn about [Backups, export and import](../production/export-and-import.md) - Learn about [Backups, export and import](export-and-import.md)
and [upgrading](../production/upgrade-or-modify.md) a production Zulip and [upgrading](upgrade-or-modify.md) a production Zulip
server. server.
[realm-admin-docs]: https://zulip.com/help/getting-your-organization-started-with-zulip [realm-admin-docs]: https://zulip.com/help/getting-your-organization-started-with-zulip

14
docs/production/maintain-secure-upgrade.md
View File

@ -9,33 +9,33 @@ have since all moved to dedicated pages:
### Monitoring ### Monitoring
Moved to [Troubleshooting](../production/troubleshooting.html#monitoring). Moved to [Troubleshooting](troubleshooting.html#monitoring).
### Securing your Zulip server ### Securing your Zulip server
Moved to [Security model](../production/security-model.md). Moved to [Security model](security-model.md).
### Upgrading ### Upgrading
Moved to [Upgrading to a release](../production/upgrade-or-modify.html#upgrading-to-a-release). Moved to [Upgrading to a release](upgrade-or-modify.html#upgrading-to-a-release).
### Upgrading from a Git repository ### Upgrading from a Git repository
Moved to [Upgrading from a Git Moved to [Upgrading from a Git
repository](../production/upgrade-or-modify.html#upgrading-from-a-git-repository). repository](upgrade-or-modify.html#upgrading-from-a-git-repository).
### Upgrading the operating system ### Upgrading the operating system
Moved to [Upgrading the operating Moved to [Upgrading the operating
system](../production/upgrade-or-modify.html#upgrading-the-operating-system). system](upgrade-or-modify.html#upgrading-the-operating-system).
### Scalability ### Scalability
Moved to [Scalability](../production/requirements.html#scalability). Moved to [Scalability](requirements.html#scalability).
### Management commands ### Management commands
Moved to [Management commands](../production/management-commands.md). Moved to [Management commands](management-commands.md).
### API and your Zulip URL ### API and your Zulip URL

8
docs/production/management-commands.md
View File

@ -52,7 +52,7 @@ containing system-internal bots like `Notification Bot`; you are
unlikely to ever need to interact with that realm.) unlikely to ever need to interact with that realm.)
Unless you are Unless you are
[hosting multiple organizations on your Zulip server](../production/multiple-organizations.md), [hosting multiple organizations on your Zulip server](multiple-organizations.md),
your single Zulip organization on the root domain will have the empty your single Zulip organization on the root domain will have the empty
string (`''`) as its `string_id`. So you can run e.g.: string (`''`) as its `string_id`. So you can run e.g.:
@ -123,7 +123,7 @@ There are dozens of useful management commands under
UI](https://zulip.com/help/change-a-users-role)) or give bots the UI](https://zulip.com/help/change-a-users-role)) or give bots the
`can_forge_sender` permission, which is needed for certain special API features. `can_forge_sender` permission, which is needed for certain special API features.
- `./manage.py export_single_user`: does a limited version of the [main - `./manage.py export_single_user`: does a limited version of the [main
export tools](../production/export-and-import.md) containing just export tools](export-and-import.md) containing just
the messages accessible by a single user. the messages accessible by a single user.
- `./manage.py reactivate_realm`: Reactivates a realm. - `./manage.py reactivate_realm`: Reactivates a realm.
- `./manage.py deactivate_user`: Deactivates a user. This can be done - `./manage.py deactivate_user`: Deactivates a user. This can be done
@ -171,12 +171,12 @@ the Zulip server.
Instead, we recommend deploying custom management commands either via Instead, we recommend deploying custom management commands either via
the [modifying Zulip][modifying-zulip] process or by storing them in the [modifying Zulip][modifying-zulip] process or by storing them in
`/etc/zulip` (so they are included in `/etc/zulip` (so they are included in
[backups](../production/export-and-import.html#backups)) and then [backups](export-and-import.html#backups)) and then
symlinking them into symlinking them into
`/home/zulip/deployments/current/zerver/management/` after each `/home/zulip/deployments/current/zerver/management/` after each
upgrade. upgrade.
[modifying-zulip]: ../production/upgrade-or-modify.html#modifying-zulip [modifying-zulip]: upgrade-or-modify.html#modifying-zulip
[writing-bots]: https://zulip.com/api/writing-bots [writing-bots]: https://zulip.com/api/writing-bots
[integrations]: https://zulip.com/integrations [integrations]: https://zulip.com/integrations
[zulip-api]: https://zulip.com/api/rest [zulip-api]: https://zulip.com/api/rest

4
docs/production/mobile-push-notifications.md
View File

@ -18,7 +18,7 @@ support forwarding push notifications to a central push notification
forwarding service. Accessing this service requires outgoing HTTPS forwarding service. Accessing this service requires outgoing HTTPS
access to the public Internet; if that is restricted by a proxy, you access to the public Internet; if that is restricted by a proxy, you
will need to [configure Zulip to use your outgoing HTTP will need to [configure Zulip to use your outgoing HTTP
proxy](../production/deployment.html#customizing-the-outgoing-http-proxy) proxy](deployment.html#customizing-the-outgoing-http-proxy)
first. first.
You can enable this for your Zulip server as follows: You can enable this for your Zulip server as follows:
@ -27,7 +27,7 @@ You can enable this for your Zulip server as follows:
`PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line `PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line
in your `/etc/zulip/settings.py` file (i.e. remove the `#` at the in your `/etc/zulip/settings.py` file (i.e. remove the `#` at the
start of the line), and [restart your Zulip start of the line), and [restart your Zulip
server](../production/settings.html#making-changes). If you server](settings.html#making-changes). If you
installed your Zulip server with a version older than 1.6, you'll installed your Zulip server with a version older than 1.6, you'll
need to add the line (it won't be there to uncomment). need to add the line (it won't be there to uncomment).

2
docs/production/multiple-organizations.md
View File

@ -55,7 +55,7 @@ the homepage for the server is a copy of the Zulip homepage.
You'll need to install an SSL certificate valid for all the You'll need to install an SSL certificate valid for all the
(sub)domains you're using your Zulip server with. You can get an SSL (sub)domains you're using your Zulip server with. You can get an SSL
certificate covering several domains for free by using certificate covering several domains for free by using
[our Certbot wrapper tool](../production/ssl-certificates.html#after-zulip-is-already-installed), [our Certbot wrapper tool](ssl-certificates.html#after-zulip-is-already-installed),
though if you're going to host a large number of organizations, you though if you're going to host a large number of organizations, you
may want to get a wildcard certificate. You can also get a wildcard may want to get a wildcard certificate. You can also get a wildcard
certificate for certificate for

2
docs/production/password-strength.md
View File

@ -8,7 +8,7 @@ When a user tries to set a password, we use [zxcvbn][zxcvbn] to check
that it isn't a weak one. that it isn't a weak one.
See discussion in [our main docs for server See discussion in [our main docs for server
admins](../production/security-model.html#passwords). This doc explains in more admins](security-model.html#passwords). This doc explains in more
detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use. detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use.
First, read the doc section there. (It's short.) First, read the doc section there. (It's short.)

2
docs/production/postgresql.md
View File

@ -10,7 +10,7 @@ included with the base operating system (E.g. PostgreSQL 12 on Ubuntu
PostgreSQL releases [upgrade to PostgreSQL 14][upgrade-postgresql], as PostgreSQL releases [upgrade to PostgreSQL 14][upgrade-postgresql], as
we may drop support for older PostgreSQL in a future release. we may drop support for older PostgreSQL in a future release.
[upgrade-postgresql]: ../production/upgrade-or-modify.html#upgrading-postgresql [upgrade-postgresql]: upgrade-or-modify.html#upgrading-postgresql
#### Remote PostgreSQL database #### Remote PostgreSQL database

22
docs/production/requirements.md
View File

@ -16,7 +16,7 @@ To run a Zulip server, you will need:
For details on each of these requirements, see below. For details on each of these requirements, see below.
[upgrade-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository [upgrade-from-git]: upgrade-or-modify.html#upgrading-from-a-git-repository
## Server ## Server
@ -52,7 +52,7 @@ sudo apt update
``` ```
[docker-zulip-homepage]: https://github.com/zulip/docker-zulip#readme [docker-zulip-homepage]: https://github.com/zulip/docker-zulip#readme
[upgrade-os]: ../production/upgrade-or-modify.html#upgrading-the-operating-system [upgrade-os]: upgrade-or-modify.html#upgrading-the-operating-system
[ubuntu-repositories]: https://help.ubuntu.com/community/Repositories/Ubuntu [ubuntu-repositories]: https://help.ubuntu.com/community/Repositories/Ubuntu
[enable-universe]: https://help.ubuntu.com/community/Repositories/CommandLine#Adding_the_Universe_and_Multiverse_Repositories [enable-universe]: https://help.ubuntu.com/community/Repositories/CommandLine#Adding_the_Universe_and_Multiverse_Repositories
@ -77,13 +77,13 @@ on hardware requirements for larger organizations.
#### Network and security specifications #### Network and security specifications
- Incoming HTTPS access (usually port 443, though this is - Incoming HTTPS access (usually port 443, though this is
[configurable](../production/deployment.html#using-an-alternate-port)) [configurable](deployment.html#using-an-alternate-port))
from the networks where your users are (usually, the public from the networks where your users are (usually, the public
Internet). Internet).
- Incoming port 80 access (optional). Zulip only serves content over - Incoming port 80 access (optional). Zulip only serves content over
HTTPS, and will redirect HTTP requests to HTTPS. HTTPS, and will redirect HTTP requests to HTTPS.
- Incoming port 25 if you plan to enable Zulip's [incoming email - Incoming port 25 if you plan to enable Zulip's [incoming email
integration](../production/email-gateway.md). integration](email-gateway.md).
- Incoming port 4369 should be protected by a firewall to prevent - Incoming port 4369 should be protected by a firewall to prevent
exposing `epmd`, an Erlang service which does not support binding exposing `epmd`, an Erlang service which does not support binding
only to localhost. Leaving this exposed will allow unauthenticated only to localhost. Leaving this exposed will allow unauthenticated
@ -95,7 +95,7 @@ on hardware requirements for larger organizations.
[disable those [disable those
features](https://zulip.com/help/allow-image-link-previews). features](https://zulip.com/help/allow-image-link-previews).
- Outgoing SMTP access (usually port 587) to your [SMTP - Outgoing SMTP access (usually port 587) to your [SMTP
server](../production/email.md) so that Zulip can send emails. server](email.md) so that Zulip can send emails.
- A domain name (e.g. `zulip.example.com`) that your users will use to - A domain name (e.g. `zulip.example.com`) that your users will use to
access the Zulip server. In order to generate valid SSL access the Zulip server. In order to generate valid SSL
certificates [with Certbot][doc-certbot], and to enable other certificates [with Certbot][doc-certbot], and to enable other
@ -111,8 +111,8 @@ on hardware requirements for larger organizations.
Zulip supports using that instead. Zulip supports using that instead.
[ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery [ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
[smokescreen-proxy]: ../production/deployment.html#customizing-the-outgoing-http-proxy [smokescreen-proxy]: deployment.html#customizing-the-outgoing-http-proxy
[reverse-proxy]: ../production/deployment.html#putting-the-zulip-application-behind-a-reverse-proxy [reverse-proxy]: deployment.html#putting-the-zulip-application-behind-a-reverse-proxy
[email-mirror-code]: https://github.com/zulip/zulip/blob/main/zerver/management/commands/email_mirror.py [email-mirror-code]: https://github.com/zulip/zulip/blob/main/zerver/management/commands/email_mirror.py
## Credentials needed ## Credentials needed
@ -145,7 +145,7 @@ certificate documentation](ssl-certificates.md).
[free outgoing SMTP options and options for prototyping](email.html#free-outgoing-email-services). [free outgoing SMTP options and options for prototyping](email.html#free-outgoing-email-services).
Once you have met these requirements, see [full instructions for installing Once you have met these requirements, see [full instructions for installing
Zulip in production](../production/install.md). Zulip in production](install.md).
[trusty-eol]: https://wiki.ubuntu.com/Releases [trusty-eol]: https://wiki.ubuntu.com/Releases
@ -167,7 +167,7 @@ server services, Django dominates the resource requirements. One can
run every service on its own system (as run every service on its own system (as
[docker-zulip](https://github.com/zulip/docker-zulip) does) but for [docker-zulip](https://github.com/zulip/docker-zulip) does) but for
most use cases, there's little scalability benefit to doing so. See most use cases, there's little scalability benefit to doing so. See
[deployment options](../production/deployment.md) for details on [deployment options](deployment.md) for details on
installing Zulip with a dedicated database server. installing Zulip with a dedicated database server.
- **Dedicated database**. For installations with hundreds of daily - **Dedicated database**. For installations with hundreds of daily
@ -240,6 +240,6 @@ For readers interested in technical details around what features
impact Zulip's scalability, this [performance and scalability design impact Zulip's scalability, this [performance and scalability design
document](../subsystems/performance.md) may also be of interest. document](../subsystems/performance.md) may also be of interest.
[s3-uploads]: ../production/upload-backends.html#s3-backend-configuration [s3-uploads]: upload-backends.html#s3-backend-configuration
[streaming-replication]: ../production/deployment.html#postgresql-warm-standby [streaming-replication]: deployment.html#postgresql-warm-standby
[contact-support]: https://zulip.com/help/contact-support [contact-support]: https://zulip.com/help/contact-support

8
docs/production/security-model.md
View File

@ -38,7 +38,7 @@ announcement).
- The preferred way to log in to Zulip is using a single sign-on (SSO) - The preferred way to log in to Zulip is using a single sign-on (SSO)
solution like Google authentication, LDAP, or similar, but Zulip solution like Google authentication, LDAP, or similar, but Zulip
also supports password authentication. See [the authentication also supports password authentication. See [the authentication
methods documentation](../production/authentication-methods.md) for methods documentation](authentication-methods.md) for
details on Zulip's available authentication methods. details on Zulip's available authentication methods.
### Passwords ### Passwords
@ -67,7 +67,7 @@ strength allowed is controlled by two settings in
By default, `PASSWORD_MIN_GUESSES` is 10000. This provides By default, `PASSWORD_MIN_GUESSES` is 10000. This provides
significant protection against online attacks, while limiting the significant protection against online attacks, while limiting the
burden imposed on users choosing a password. See burden imposed on users choosing a password. See
[password strength](../production/password-strength.md) for an extended [password strength](password-strength.md) for an extended
discussion on how we chose this value. discussion on how we chose this value.
Estimating the guessability of a password is a complex problem and Estimating the guessability of a password is a complex problem and
@ -272,8 +272,8 @@ strength allowed is controlled by two settings in
[go-camo]: https://github.com/cactus/go-camo [go-camo]: https://github.com/cactus/go-camo
[ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery [ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
[smokescreen-setup]: ../production/deployment.html#customizing-the-outgoing-http-proxy [smokescreen-setup]: deployment.html#customizing-the-outgoing-http-proxy
[proxy.enable_for_camo]: ../production/deployment.html#enable-for-camo [proxy.enable_for_camo]: deployment.html#enable-for-camo
## Final notes and security response ## Final notes and security response

12
docs/production/settings.md
View File

@ -28,7 +28,7 @@ from an old version of Zulip, we recommend [carefully updating your
comment documentation for new configuration settings after upgrading comment documentation for new configuration settings after upgrading
to each new major release. to each new major release.
[update-settings-docs]: ../production/upgrade-or-modify.html#updating-settings-py-inline-documentation [update-settings-docs]: upgrade-or-modify.html#updating-settings-py-inline-documentation
[settings-py-template]: https://github.com/zulip/zulip/blob/main/zproject/prod_settings_template.py [settings-py-template]: https://github.com/zulip/zulip/blob/main/zproject/prod_settings_template.py
Since Zulip's settings file is a Python script, there are a number of Since Zulip's settings file is a Python script, there are a number of
@ -61,7 +61,7 @@ If you want an additional or different authentication backend, you
will need to uncomment one or more and then do any additional will need to uncomment one or more and then do any additional
configuration required for that backend as documented in the configuration required for that backend as documented in the
`settings.py` file. See the `settings.py` file. See the
[section on authentication](../production/authentication-methods.md) for more [section on authentication](authentication-methods.md) for more
detail on the available authentication backends and how to configure detail on the available authentication backends and how to configure
them. them.
@ -112,9 +112,9 @@ Some popular settings in `/etc/zulip/settings.py` include:
- The Twitter integration, which provides pretty inline previews of - The Twitter integration, which provides pretty inline previews of
tweets. tweets.
- The [email gateway](../production/email-gateway.md), which lets - The [email gateway](email-gateway.md), which lets
users send emails into Zulip. users send emails into Zulip.
- The [Video call integrations](../production/video-calls.md). - The [Video call integrations](video-calls.md).
## Zulip announcement list ## Zulip announcement list
@ -132,5 +132,5 @@ request; we love even small contributions, and we'd love to make the
Zulip documentation cover everything anyone might want to know about Zulip documentation cover everything anyone might want to know about
running Zulip in production. running Zulip in production.
Next: [Backups, export and import](../production/export-and-import.md) and Next: [Backups, export and import](export-and-import.md) and
[upgrading](../production/upgrade-or-modify.md) Zulip in production. [upgrading](upgrade-or-modify.md) Zulip in production.

2
docs/production/ssl-certificates.md
View File

@ -81,7 +81,7 @@ Internet.
If you need to configure a multiple domain certificate, you can generate If you need to configure a multiple domain certificate, you can generate
one as described in the section below after installing Zulip. one as described in the section below after installing Zulip.
[doc-install-script]: ../production/install.html#step-2-install-zulip [doc-install-script]: install.html#step-2-install-zulip
### After Zulip is already installed ### After Zulip is already installed

8
docs/production/upgrade-or-modify.md
View File

@ -60,7 +60,7 @@ involved (these will be documented in the [release
notes](../overview/changelog.md), and usually can be avoided with notes](../overview/changelog.md), and usually can be avoided with
some care). If downtime is problematic for your organization, some care). If downtime is problematic for your organization,
consider testing the upgrade on a consider testing the upgrade on a
[backup](../production/export-and-import.html#backups) in advance, [backup](export-and-import.html#backups) in advance,
doing the final upgrade at off hours, or buying a support contract. doing the final upgrade at off hours, or buying a support contract.
See the [troubleshooting guide](#troubleshooting-and-rollback) if you See the [troubleshooting guide](#troubleshooting-and-rollback) if you
@ -156,13 +156,13 @@ suggest using that updated template to update
su zulip -c '/home/zulip/deployments/current/scripts/restart-server' su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
``` ```
[backups]: ../production/export-and-import.html#backups [backups]: export-and-import.html#backups
[changelog]: ../overview/changelog.md [changelog]: ../overview/changelog.md
## Troubleshooting and rollback ## Troubleshooting and rollback
See also the general Zulip server [troubleshooting See also the general Zulip server [troubleshooting
guide](../production/troubleshooting.md). guide](troubleshooting.md).
The upgrade scripts are idempotent, so there's no harm in trying again The upgrade scripts are idempotent, so there's no harm in trying again
after resolving an issue. The most common causes of errors are: after resolving an issue. The most common causes of errors are:
@ -800,7 +800,7 @@ upgrading to `main`, make sure you understand:
- We do not support downgrading from `main` to earlier versions, so - We do not support downgrading from `main` to earlier versions, so
if downtime for your Zulip server is unacceptable, make sure you if downtime for your Zulip server is unacceptable, make sure you
have a current have a current
[backup](../production/export-and-import.html#backups) in case the [backup](export-and-import.html#backups) in case the
upgrade fails. upgrade fails.
- Our changelog contains [draft release - Our changelog contains [draft release
notes](../overview/changelog.md) available listing major changes notes](../overview/changelog.md) available listing major changes

2
docs/subsystems/api-release-checklist.md
View File

@ -50,7 +50,7 @@ checklist of things one must do before making a PyPI release:
See [the tag][example-tag] and [the commit][example-commit] for the 0.8.1 release See [the tag][example-tag] and [the commit][example-commit] for the 0.8.1 release
to see an example. to see an example.
Now it is time to [update the dependencies](../subsystems/dependencies) in the Now it is time to [update the dependencies](dependencies) in the
[Zulip server repository][zulip-repo]: [Zulip server repository][zulip-repo]:
1. Increment `PROVISION_VERSION` in `version.py`. A minor version bump should suffice in 1. Increment `PROVISION_VERSION` in `version.py`. A minor version bump should suffice in

2
docs/subsystems/caching.md
View File

@ -256,7 +256,7 @@ avatars, similar details for streams, recent message history, etc.
This data is fetched in the `/register` endpoint (or `page_params` This data is fetched in the `/register` endpoint (or `page_params`
for the web app), and kept correct over time. The key to keeping these for the web app), and kept correct over time. The key to keeping these
state up to date is Zulip's state up to date is Zulip's
[real-time events system](../subsystems/events-system.md), which [real-time events system](events-system.md), which
allows the server to notify clients whenever state that might be allows the server to notify clients whenever state that might be
cached by clients is changed. Clients are responsible for handling cached by clients is changed. Clients are responsible for handling
the events, updating their state, and rerendering any UI components the events, updating their state, and rerendering any UI components

2
docs/subsystems/client.md
View File

@ -13,7 +13,7 @@ of Zulip; it's primarily intended to assist debugging.
A `Client` is used to sort messages into client categories such as A `Client` is used to sort messages into client categories such as
`ZulipElectron` on the `/stats` page. For more information see, `ZulipElectron` on the `/stats` page. For more information see,
[Analytics](../subsystems/analytics.md). [Analytics](analytics.md).
## Integrations ## Integrations

4
docs/subsystems/dependencies.md
View File

@ -232,7 +232,7 @@ reasoning here.
dependencies in the `yarn.lock` file; `yarn install` updates the dependencies in the `yarn.lock` file; `yarn install` updates the
`yarn.lock` files. `yarn.lock` files.
- `tools/update-prod-static`. This process is discussed in detail in - `tools/update-prod-static`. This process is discussed in detail in
the [static asset pipeline](../subsystems/html-css.html#static-asset-pipeline) the [static asset pipeline](html-css.html#static-asset-pipeline)
article, but we don't use the `node_modules` directories directly in article, but we don't use the `node_modules` directories directly in
production. Instead, static assets are compiled using our static production. Instead, static assets are compiled using our static
asset pipeline and it is the compiled assets that are served asset pipeline and it is the compiled assets that are served
@ -290,7 +290,7 @@ Zulip uses the [iamcal emoji data package][iamcal] for its emoji data
and sprite sheets. We download this dependency using `npm`, and then and sprite sheets. We download this dependency using `npm`, and then
have a tool, `tools/setup/build_emoji`, which reformats the emoji data have a tool, `tools/setup/build_emoji`, which reformats the emoji data
into the files under `static/generated/emoji`. Those files are in into the files under `static/generated/emoji`. Those files are in
turn used by our [Markdown processor](../subsystems/markdown.md) and turn used by our [Markdown processor](markdown.md) and
`tools/update-prod-static` to make Zulip's emoji work in the various `tools/update-prod-static` to make Zulip's emoji work in the various
environments where they need to be displayed. environments where they need to be displayed.

2
docs/subsystems/email.md
View File

@ -44,7 +44,7 @@ Email takes about a quarter second per email to process and send. Generally
speaking, if you're sending just one email, doing it in the current process speaking, if you're sending just one email, doing it in the current process
is fine. If you're sending emails in a loop, you probably want to send it is fine. If you're sending emails in a loop, you probably want to send it
from a queue. Documentation on our queueing system is available from a queue. Documentation on our queueing system is available
[here](../subsystems/queuing.md). [here](queuing.md).
## Development and testing ## Development and testing

4
docs/subsystems/emoji.md
View File

@ -64,7 +64,7 @@ The `build_emoji` tool generates the set of files under
`static/generated/emoji` is a symlink to that tree; we do this in `static/generated/emoji` is a symlink to that tree; we do this in
order to cache old versions to make provisioning and production order to cache old versions to make provisioning and production
deployments super fast in the common case that we haven't changed the deployments super fast in the common case that we haven't changed the
emoji tooling). See [our dependencies document](../subsystems/dependencies.md) emoji tooling). See [our dependencies document](dependencies.md)
for more details on this strategy. for more details on this strategy.
The emoji tree generated by this process contains several import elements: The emoji tree generated by this process contains several import elements:
@ -80,7 +80,7 @@ The emoji tree generated by this process contains several import elements:
- `images/emoji/*.png`: A farm of symlinks from emoji names to the - `images/emoji/*.png`: A farm of symlinks from emoji names to the
`images/emoji/unicode/` tree. This is used to serve individual emoji `images/emoji/unicode/` tree. This is used to serve individual emoji
images, as well as for the images, as well as for the
[backend Markdown processor](../subsystems/markdown.md) to know which emoji [backend Markdown processor](markdown.md) to know which emoji
names exist and what Unicode emoji / images they map to. In this names exist and what Unicode emoji / images they map to. In this
tree, we currently include all of the emoji in `emoji-map.json`; tree, we currently include all of the emoji in `emoji-map.json`;
this means that if you send `:angry_face:`, it won't autocomplete, this means that if you send `:angry_face:`, it won't autocomplete,

4
docs/subsystems/events-system.md
View File

@ -162,7 +162,7 @@ its data, clients would recover, just as if they had lost Internet
access briefly (there is some DoS risk to manage, though). access briefly (there is some DoS risk to manage, though).
Note that the garbage-collection system has hooks that are important Note that the garbage-collection system has hooks that are important
for the implementation of [notifications](../subsystems/notifications.md). for the implementation of [notifications](notifications.md).
(The event queue server is designed to save any event queues to disk (The event queue server is designed to save any event queues to disk
and reload them when the server is restarted, and catches exceptions and reload them when the server is restarted, and catches exceptions
@ -407,7 +407,7 @@ correctly, clients are responsible for discarding events related to
messages that the client has not yet fetched. messages that the client has not yet fetched.
Additionally, see Additionally, see
[the main documentation on sending messages](../subsystems/sending-messages.md). [the main documentation on sending messages](sending-messages.md).
## Schema changes ## Schema changes

2
docs/subsystems/hashchange-system.md
View File

@ -121,4 +121,4 @@ box as a draft).
[testing-with-puppeteer]: ../testing/testing-with-puppeteer.md [testing-with-puppeteer]: ../testing/testing-with-puppeteer.md
[self-server-reloads]: #server-initiated-reloads [self-server-reloads]: #server-initiated-reloads
[events-system]: ../subsystems/events-system.md [events-system]: events-system.md

2
docs/subsystems/html-css.md
View File

@ -145,7 +145,7 @@ developing new features for Zulip that require front-end changes,
especially those that involve adding new files. For a more general especially those that involve adding new files. For a more general
overview, see the [new feature tutorial](../tutorials/new-feature-tutorial.md). overview, see the [new feature tutorial](../tutorials/new-feature-tutorial.md).
Our [dependencies documentation](../subsystems/dependencies.md) has useful Our [dependencies documentation](dependencies.md) has useful
relevant background as well. relevant background as well.
### Primary build process ### Primary build process

2
docs/subsystems/logging.md
View File

@ -167,7 +167,7 @@ and report to the server the following whenever a message is sent:
- Whether the message was locally echoed. - Whether the message was locally echoed.
- If so, whether there was a disparity between the echoed content and - If so, whether there was a disparity between the echoed content and
the server-rendered content, which can be used for statistics on how the server-rendered content, which can be used for statistics on how
effective our [local echo system](../subsystems/markdown.md) is. effective our [local echo system](markdown.md) is.
The code is all in `zerver/lib/report.py` and `static/js/sent_messages.js`. The code is all in `zerver/lib/report.py` and `static/js/sent_messages.js`.

6
docs/subsystems/notifications.md
View File

@ -3,7 +3,7 @@
This is a design document aiming to provide context for developers This is a design document aiming to provide context for developers
working on Zulip's email notifications and mobile push notifications working on Zulip's email notifications and mobile push notifications
code paths. We recommend first becoming familiar with [sending code paths. We recommend first becoming familiar with [sending
messages](../subsystems/sending-messages.md); this document expands on messages](sending-messages.md); this document expands on
the details of the email/mobile push notifications code path. the details of the email/mobile push notifications code path.
## Important corner cases ## Important corner cases
@ -43,7 +43,7 @@ as follows:
structure ignores users for whom the message is not notifiable, structure ignores users for whom the message is not notifiable,
which is important to avoid this being thousands of `user_ids` for which is important to avoid this being thousands of `user_ids` for
messages to large streams with few currently active users. messages to large streams with few currently active users.
- The Tornado [event queue system](../subsystems/events-system.md) - The Tornado [event queue system](events-system.md)
processes that data, as well as data about each user's active event processes that data, as well as data about each user's active event
queues, to (1) push an event to each queue needing that message and queues, to (1) push an event to each queue needing that message and
(2) for notifiable messages, pushing an event onto the (2) for notifiable messages, pushing an event onto the
@ -64,7 +64,7 @@ as follows:
if a user was present 1 minute before a message was sent, and then if a user was present 1 minute before a message was sent, and then
closed their laptop, the user will not be in closed their laptop, the user will not be in
`presence_idle_user_ids` (because it takes a `presence_idle_user_ids` (because it takes a
[few minutes](../subsystems/presence.md) of being idle for Zulip [few minutes](presence.md) of being idle for Zulip
clients to declare to the server that the user is actually idle), clients to declare to the server that the user is actually idle),
and so without an additional mechanism, messages sent shortly after and so without an additional mechanism, messages sent shortly after
a user leaves would never trigger a notification (!). a user leaves would never trigger a notification (!).

18
docs/subsystems/performance.md
View File

@ -38,7 +38,7 @@ of load profiles:
example for this, with more than 15K total user accounts, of which example for this, with more than 15K total user accounts, of which
only several hundred have logged in during the last few weeks. only several hundred have logged in during the last few weeks.
Zulip has many important optimizations, including [soft Zulip has many important optimizations, including [soft
deactivation](../subsystems/sending-messages.html#soft-deactivation) deactivation](sending-messages.html#soft-deactivation)
to ensure idle users have minimal impact on both server-side to ensure idle users have minimal impact on both server-side
scalability and request latency. scalability and request latency.
- Fulltime teams, like your typical corporate Zulip installation, - Fulltime teams, like your typical corporate Zulip installation,
@ -114,7 +114,7 @@ is negligible.
### Tornado ### Tornado
Zulip's Tornado-based [real-time push Zulip's Tornado-based [real-time push
system](../subsystems/events-system.md), and in particular system](events-system.md), and in particular
`GET /events`, accounts for something like 50% of all HTTP requests to `GET /events`, accounts for something like 50% of all HTTP requests to
a production Zulip server. Despite `GET /events` being extremely a production Zulip server. Despite `GET /events` being extremely
high-volume, the typical request takes 1-3ms to process, and doesn't high-volume, the typical request takes 1-3ms to process, and doesn't
@ -149,7 +149,7 @@ thousands of concurrent users.
presence information and return the information for all other active presence information and return the information for all other active
users in the organization, account for about 36% of all HTTP requests users in the organization, account for about 36% of all HTTP requests
on production Zulip servers. See on production Zulip servers. See
[presence](../subsystems/presence.md) for details on this system and [presence](presence.md) for details on this system and
how it's optimized. For this article, it's important to know that how it's optimized. For this article, it's important to know that
presence is one of the most important scalability concerns for any presence is one of the most important scalability concerns for any
chat system, because it cannot be cached long, and is structurally a chat system, because it cannot be cached long, and is structurally a
@ -249,7 +249,7 @@ it does a large number of these requests:
zulip.com, this can result in a thundering herd effect for both `/` zulip.com, this can result in a thundering herd effect for both `/`
and `GET /messages`. A great deal of care has been taking in and `GET /messages`. A great deal of care has been taking in
designing this [auto-reload designing this [auto-reload
system](../subsystems/hashchange-system.html#server-initiated-reloads) system](hashchange-system.html#server-initiated-reloads)
to spread most of that herd over several minutes. to spread most of that herd over several minutes.
Typical requests consume 20-100ms to process, much of which is waiting Typical requests consume 20-100ms to process, much of which is waiting
@ -295,7 +295,7 @@ as it navigates around the app.
### Sending and editing messages ### Sending and editing messages
[Sending new messages](../subsystems/sending-messages.md) (including [Sending new messages](sending-messages.md) (including
incoming webhooks) represents less than 0.5% of total request volume. incoming webhooks) represents less than 0.5% of total request volume.
That this number is small should not be surprising even though sending That this number is small should not be surprising even though sending
messages is intuitively the main feature of a chat service: a message messages is intuitively the main feature of a chat service: a message
@ -303,7 +303,7 @@ sent to 50 users triggers ~50 `GET /events` requests.
A typical message-send request takes 20-70ms, with more expensive A typical message-send request takes 20-70ms, with more expensive
requests typically resulting from [Markdown requests typically resulting from [Markdown
rendering](../subsystems/markdown.md) of more complex syntax. As a rendering](markdown.md) of more complex syntax. As a
result, these requests are not material to Zulip's scalability. result, these requests are not material to Zulip's scalability.
Editing messages and adding emoji reactions are very similar to Editing messages and adding emoji reactions are very similar to
sending them for the purposes of performance and scalability, since sending them for the purposes of performance and scalability, since
@ -335,7 +335,7 @@ scalability of a Zulip server.
The above doesn't cover all of the work that a production Zulip server The above doesn't cover all of the work that a production Zulip server
does; various tasks like sending outgoing emails or recording the data does; various tasks like sending outgoing emails or recording the data
that powers [/stats](https://zulip.com/help/analytics) are run by that powers [/stats](https://zulip.com/help/analytics) are run by
[queue processors](../subsystems/queuing.md) and cron jobs, not in [queue processors](queuing.md) and cron jobs, not in
response to incoming HTTP requests. In practice, all of these have response to incoming HTTP requests. In practice, all of these have
been written such that they are immaterial to total load and thus been written such that they are immaterial to total load and thus
architectural scalability, though we do from time to time need to do architectural scalability, though we do from time to time need to do
@ -358,7 +358,7 @@ Python/CPU time (being harder to scale horizontally).
Most optimizations to make an endpoint cheaper will start with Most optimizations to make an endpoint cheaper will start with
optimizing the database queries and/or employing optimizing the database queries and/or employing
[caching](../subsystems/caching.md), and then continue as needed with [caching](caching.md), and then continue as needed with
profiling of the Python code and any memcached queries. profiling of the Python code and any memcached queries.
For a handful of the critical code paths listed above, we further For a handful of the critical code paths listed above, we further
@ -367,7 +367,7 @@ for narrow sections; typically this is sufficient to result in the
database query time dominating that spent by the Python application database query time dominating that spent by the Python application
server process. server process.
Zulip's [server logs](../subsystems/logging.md) are designed to Zulip's [server logs](logging.md) are designed to
provide insight when a request consumes significant database or provide insight when a request consumes significant database or
memcached resources, which is useful both in development and in memcached resources, which is useful both in development and in
production. production.

20
docs/subsystems/sending-messages.md
View File

@ -7,7 +7,7 @@ experience.
This document aims to explain conceptually what happens when a message This document aims to explain conceptually what happens when a message
is sent in Zulip, and why that is correct behavior. It assumes the is sent in Zulip, and why that is correct behavior. It assumes the
reader is familiar with our reader is familiar with our
[real-time sync system](../subsystems/events-system.md) for [real-time sync system](events-system.md) for
server-to-client communication and server-to-client communication and
[new application feature tutorial](../tutorials/new-feature-tutorial.md), [new application feature tutorial](../tutorials/new-feature-tutorial.md),
and we generally don't repeat the content discussed there. and we generally don't repeat the content discussed there.
@ -53,13 +53,13 @@ This section details the ways in which it is different:
function in `zerver/tornado/event_queue.py`. This custom code has a function in `zerver/tornado/event_queue.py`. This custom code has a
number of purposes: number of purposes:
- Triggering [email and mobile push - Triggering [email and mobile push
notifications](../subsystems/notifications.md) for any users who notifications](notifications.md) for any users who
do not have active clients and have settings of the form "push do not have active clients and have settings of the form "push
notifications when offline". In order to avoid doing any real notifications when offline". In order to avoid doing any real
computational work inside the Tornado codebase, this logic aims computational work inside the Tornado codebase, this logic aims
to just do the check for whether a notification should be to just do the check for whether a notification should be
generated, and then put an event into an appropriate generated, and then put an event into an appropriate
[queue](../subsystems/queuing.md) to actually send the message. [queue](queuing.md) to actually send the message.
See `maybe_enqueue_notifications` and `zerver/lib/notification_data.py` for See `maybe_enqueue_notifications` and `zerver/lib/notification_data.py` for
this part of the logic. this part of the logic.
- Splicing user-dependent data (E.g. `flags` such as when the user - Splicing user-dependent data (E.g. `flags` such as when the user
@ -73,7 +73,7 @@ This section details the ways in which it is different:
- Following our standard naming convention, input validation is done - Following our standard naming convention, input validation is done
inside the `check_message` function in `zerver/lib/actions.py`, which is responsible for inside the `check_message` function in `zerver/lib/actions.py`, which is responsible for
validating the user can send to the recipient, validating the user can send to the recipient,
[rendering the Markdown](../subsystems/markdown.md), etc. -- [rendering the Markdown](markdown.md), etc. --
basically everything that can fail due to bad user input. basically everything that can fail due to bad user input.
- The core `do_send_messages` function (which handles actually sending - The core `do_send_messages` function (which handles actually sending
the message) in `zerver/lib/actions.py` is one of the most optimized and thus complex parts of the message) in `zerver/lib/actions.py` is one of the most optimized and thus complex parts of
@ -89,7 +89,7 @@ This section details the ways in which it is different:
open organizations. open organizations.
- Do all the database queries to fetch relevant data for and then - Do all the database queries to fetch relevant data for and then
send a `message` event to the send a `message` event to the
[events system](../subsystems/events-system.md) containing the [events system](events-system.md) containing the
data it will need for the calculations described above. This data it will need for the calculations described above. This
step adds a lot of complexity, because the events system cannot step adds a lot of complexity, because the events system cannot
make queries to the database directly. make queries to the database directly.
@ -115,7 +115,7 @@ browser, and then replace it with data from the server when it
changes. changes.
Zulip aims for a near-perfect local echo experience, which requires is Zulip aims for a near-perfect local echo experience, which requires is
why our [Markdown system](../subsystems/markdown.md) requires both why our [Markdown system](markdown.md) requires both
an authoritative (backend) Markdown implementation and a secondary an authoritative (backend) Markdown implementation and a secondary
(frontend) Markdown implementation, the latter used only for the local (frontend) Markdown implementation, the latter used only for the local
echo feature. Read our Markdown documentation for all the tricky echo feature. Read our Markdown documentation for all the tricky
@ -151,7 +151,7 @@ messages.
unique value within that namespace identifying the message. unique value within that namespace identifying the message.
- The `do_send_messages` backend code path includes the `queue_id` and - The `do_send_messages` backend code path includes the `queue_id` and
`local_id` in the data it passes to the `local_id` in the data it passes to the
[events system](../subsystems/events-system.md). The events [events system](events-system.md). The events
system will extend the `message` event dictionary it delivers to system will extend the `message` event dictionary it delivers to
the client containing the `queue_id` with `local_message_id` field, the client containing the `queue_id` with `local_message_id` field,
containing the `local_id` that the relevant client used when sending containing the `local_id` that the relevant client used when sending
@ -238,7 +238,7 @@ users.
message without including the URL embeds/previews, but it will add a message without including the URL embeds/previews, but it will add a
deferred work item into the `embed_links` queue. deferred work item into the `embed_links` queue.
- The [queue processor](../subsystems/queuing.md) for the - The [queue processor](queuing.md) for the
`embed_links` queue will fetch the URLs, and then if they return `embed_links` queue will fetch the URLs, and then if they return
results, rerun the Markdown processor and notify clients of the results, rerun the Markdown processor and notify clients of the
updated message `rendered_content`. updated message `rendered_content`.
@ -286,7 +286,7 @@ latency was unacceptable: The server backend was introducing a latency
of about 1 second per 2000 users subscribed to receive the message. of about 1 second per 2000 users subscribed to receive the message.
While these delays may not be immediately obvious to users (Zulip, While these delays may not be immediately obvious to users (Zulip,
like many other chat applications, like many other chat applications,
[local echoes](../subsystems/markdown.md) messages that a user sends [local echoes](markdown.md) messages that a user sends
as soon as the user hits “Send”), latency beyond a second or two as soon as the user hits “Send”), latency beyond a second or two
significantly impacts the feeling of interactivity in a chat significantly impacts the feeling of interactivity in a chat
experience (i.e. it feels like everyone takes a long time to reply to experience (i.e. it feels like everyone takes a long time to reply to
@ -378,7 +378,7 @@ the extra 4500 inactive subscribers didn’t exist.
There are a few details that require special care with this system: There are a few details that require special care with this system:
- [Email and mobile push - [Email and mobile push
notifications](../subsystems/notifications.md). We need to make notifications](notifications.md). We need to make
sure these are still correctly delivered to soft-deactivated users; sure these are still correctly delivered to soft-deactivated users;
making this work required careful work for those code paths that making this work required careful work for those code paths that
assumed a `UserMessage` row would always exist for a message that assumed a `UserMessage` row would always exist for a message that

2
docs/subsystems/typing-indicators.md
View File

@ -69,7 +69,7 @@ how long they pause to think, and how frequently they get interrupted.
The server piece of typing notifications is currently pretty The server piece of typing notifications is currently pretty
straightforward, since we take advantage of Zulip's straightforward, since we take advantage of Zulip's
[events system](../subsystems/events-system.md). [events system](events-system.md).
We deliberately designed the server piece to be stateless, We deliberately designed the server piece to be stateless,
which minimizes the possibility of backend bugs and gives clients which minimizes the possibility of backend bugs and gives clients

2
docs/testing/continuous-integration.md
View File

@ -64,7 +64,7 @@ depend on the version of the base OS and/or Python.
Our code for running the tests in CI lives under `tools/ci`; but that Our code for running the tests in CI lives under `tools/ci`; but that
logic is mostly thin wrappers around [Zulip's test logic is mostly thin wrappers around [Zulip's test
suites](../testing/testing.md) or production installer. suites](testing.md) or production installer.
The `Legacy OS` tests are designed to ensure we give good error The `Legacy OS` tests are designed to ensure we give good error
messages when trying to upgrade Zulip servers running on very old base messages when trying to upgrade Zulip servers running on very old base

4
docs/testing/linters.md
View File

@ -101,7 +101,7 @@ find limitations in either the Zulip home-grown stuff or our third party
tools, feedback will be highly appreciated. tools, feedback will be highly appreciated.
Finally, one way to clean up your code is to thoroughly exercise it Finally, one way to clean up your code is to thoroughly exercise it
with tests. The [Zulip test documentation](../testing/testing.md) with tests. The [Zulip test documentation](testing.md)
describes our test system in detail. describes our test system in detail.
## Lint checks ## Lint checks
@ -120,7 +120,7 @@ following checks:
- Check CSS for parsability and formatting. - Check CSS for parsability and formatting.
- Check JavaScript code for addClass calls. - Check JavaScript code for addClass calls.
- Running `mypy` to check static types in Python code. Our - Running `mypy` to check static types in Python code. Our
[documentation on using mypy](../testing/mypy.md) covers mypy in [documentation on using mypy](mypy.md) covers mypy in
more detail. more detail.
- Running `tsc` to compile TypeScript code. Our [documentation on - Running `tsc` to compile TypeScript code. Our [documentation on
TypeScript](typescript.md) covers TypeScript in more detail. TypeScript](typescript.md) covers TypeScript in more detail.

4
docs/testing/testing-with-node.md
View File

@ -2,7 +2,7 @@
Our node-based unit tests system is the preferred way to test Our node-based unit tests system is the preferred way to test
JavaScript/TypeScript code in Zulip. We prefer it over the [Puppeteer JavaScript/TypeScript code in Zulip. We prefer it over the [Puppeteer
black-box whole-app testing](../testing/testing-with-puppeteer.md), black-box whole-app testing](testing-with-puppeteer.md),
system since it is much (>100x) faster and also easier to do correctly system since it is much (>100x) faster and also easier to do correctly
than the Puppeteer system. than the Puppeteer system.
@ -50,7 +50,7 @@ A good first test to read is
## How the node tests work ## How the node tests work
Unlike the [Puppeteer unit tests](../testing/testing-with-puppeteer.md), Unlike the [Puppeteer unit tests](testing-with-puppeteer.md),
which use a headless Chromium browser connected to a running Zulip which use a headless Chromium browser connected to a running Zulip
development server, our node unit tests don't have a browser, don't development server, our node unit tests don't have a browser, don't
talk to a server, and generally don't use a complete virtual DOM (a talk to a server, and generally don't use a complete virtual DOM (a

6
docs/testing/testing-with-puppeteer.md
View File

@ -1,6 +1,6 @@
# Web frontend black-box Puppeteer tests # Web frontend black-box Puppeteer tests
While our [node test suite](../testing/testing-with-node.md) is the While our [node test suite](testing-with-node.md) is the
preferred way to test most frontend code because they are easy to preferred way to test most frontend code because they are easy to
write and maintain, some code is best tested in a real browser, either write and maintain, some code is best tested in a real browser, either
because of navigation (E.g. login) or because we want to verify the because of navigation (E.g. login) or because we want to verify the
@ -64,7 +64,7 @@ familiar with [async/await][learn-async-await].
The following questions are useful when debugging Puppeteer test The following questions are useful when debugging Puppeteer test
failures you might see in [continuous failures you might see in [continuous
integration](../testing/continuous-integration.md): integration](continuous-integration.md):
- Does the flow being tested work properly in the Zulip browser UI? - Does the flow being tested work properly in the Zulip browser UI?
Test failures can reflect real bugs, and often it's easier and more Test failures can reflect real bugs, and often it's easier and more
@ -159,7 +159,7 @@ notes above:
- The test suite uses a smaller set of default user accounts and other - The test suite uses a smaller set of default user accounts and other
data initialized in the database than the normal development data initialized in the database than the normal development
environment; specifically, it uses the same setup as the [backend environment; specifically, it uses the same setup as the [backend
tests](../testing/testing-with-django.md). To see what differs from tests](testing-with-django.md). To see what differs from
the development environment, check out the conditions on the development environment, check out the conditions on
`options["test_suite"]` in `options["test_suite"]` in
`zilencer/management/commands/populate_db.py`. `zilencer/management/commands/populate_db.py`.

14
docs/testing/testing.md
View File

@ -8,9 +8,9 @@ similar.
This page focused on the mechanics of running automated tests in a This page focused on the mechanics of running automated tests in a
[development environment](../development/overview.md); you may also [development environment](../development/overview.md); you may also
want to read about our [testing philosophy](../testing/philosophy.md) want to read about our [testing philosophy](philosophy.md)
and [continuous integration and [continuous integration
setup](../testing/continuous-integration.md). setup](continuous-integration.md).
Manual testing with a web browser is primarily discussed in the docs Manual testing with a web browser is primarily discussed in the docs
on [using the development environment](../development/using.md). on [using the development environment](../development/using.md).
@ -48,11 +48,11 @@ useful options are discussed in each tool's documentation (e.g.
Zulip has a handful of major tests suite that every developer will Zulip has a handful of major tests suite that every developer will
eventually work with, each with its own page detailing how it works: eventually work with, each with its own page detailing how it works:
- [Linters](../testing/linters.md): Our dozen or so linters run in parallel. - [Linters](linters.md): Our dozen or so linters run in parallel.
- [Django](../testing/testing-with-django.md): Server/backend Python tests. - [Django](testing-with-django.md): Server/backend Python tests.
- [Node](../testing/testing-with-node.md): JavaScript tests for the - [Node](testing-with-node.md): JavaScript tests for the
frontend run via node.js. frontend run via node.js.
- [Puppeteer](../testing/testing-with-puppeteer.md): End-to-end - [Puppeteer](testing-with-puppeteer.md): End-to-end
UI tests run via a Chromium browser. UI tests run via a Chromium browser.
## Other test suites ## Other test suites
@ -126,7 +126,7 @@ This is easy to do using test fixtures (a fancy word for fixed data
used in tests) and the `mock.patch` function to specify what HTTP used in tests) and the `mock.patch` function to specify what HTTP
response should be used by the tests for every outgoing HTTP (or other response should be used by the tests for every outgoing HTTP (or other
network) request. Consult network) request. Consult
[our guide on mocking](../testing/testing-with-django.html#zulip-mocking-practices) to [our guide on mocking](testing-with-django.html#zulip-mocking-practices) to
learn how to mock network requests easily; there are also a number of learn how to mock network requests easily; there are also a number of
examples throughout the codebase. examples throughout the codebase.

2
docs/testing/typescript.md
View File

@ -4,7 +4,7 @@ Zulip is early in the process of migrating our codebase to use
[TypeScript](https://www.typescriptlang.org/), the leading static type [TypeScript](https://www.typescriptlang.org/), the leading static type
system for JavaScript. It works as an extension of the ES6 JavaScript system for JavaScript. It works as an extension of the ES6 JavaScript
standard, and provides similar benefits to our use of standard, and provides similar benefits to our use of
[the mypy static type system for Python](../testing/mypy.md). [the mypy static type system for Python](mypy.md).
We expect to eventually migrate the entire JavaScript codebase to We expect to eventually migrate the entire JavaScript codebase to
TypeScript, though our current focus is on getting the tooling and TypeScript, though our current focus is on getting the tooling and

4
docs/translating/internationalization.md
View File

@ -26,7 +26,7 @@ principles are important in how we think about internationalization:
element needs to be built in a way that supports i18n. element needs to be built in a way that supports i18n.
- This is more about string consistency in general, but we have a - This is more about string consistency in general, but we have a
"Sentence case" [capitalization "Sentence case" [capitalization
policy](../translating/translating.html#capitalization) that we enforce using linters policy](translating.html#capitalization) that we enforce using linters
that check all strings tagged for translation in Zulip. that check all strings tagged for translation in Zulip.
This article aims to provide a brief introduction. We recommend the This article aims to provide a brief introduction. We recommend the
@ -108,7 +108,7 @@ The end-to-end tooling process for translations in Zulip is as follows.
Transifex API tool, `tx pull`, internally). Transifex API tool, `tx pull`, internally).
If you're interested, you may also want to check out the [translators' If you're interested, you may also want to check out the [translators'
workflow](../translating/translating.html#translators-workflow), just so you have a workflow](translating.html#translators-workflow), just so you have a
sense of how everything fits together. sense of how everything fits together.
## Translation resource files ## Translation resource files

4
docs/translating/translating.md
View File

@ -13,7 +13,7 @@ greatly appreciated!
If you are interested in knowing about the technical end-to-end If you are interested in knowing about the technical end-to-end
tooling and processes for tagging strings for translation and syncing tooling and processes for tagging strings for translation and syncing
translations in Zulip, read about [Internationalization for translations in Zulip, read about [Internationalization for
Developers](../translating/internationalization.md). Developers](internationalization.md).
## Translators' workflow ## Translators' workflow
@ -115,7 +115,7 @@ can usually just deploy the latest translations there.
- First, download the updated resource files from Transifex using the - First, download the updated resource files from Transifex using the
`tools/i18n/sync-translations` command (it will require some [initial `tools/i18n/sync-translations` command (it will require some [initial
setup](../translating/internationalization.html#transifex-cli-setup)). This setup](internationalization.html#transifex-cli-setup)). This
command will download the resource files from Transifex and replace command will download the resource files from Transifex and replace
your local resource files with them, and then compile them. You can your local resource files with them, and then compile them. You can
now test your translation work in the Zulip UI. now test your translation work in the Zulip UI.

4
docs/tutorials/writing-views.md
View File

@ -3,14 +3,14 @@
## What this covers ## What this covers
This page documents how views work in Zulip. You may want to read the This page documents how views work in Zulip. You may want to read the
[new feature tutorial](../tutorials/new-feature-tutorial.md) [new feature tutorial](new-feature-tutorial.md)
and treat this as a reference. and treat this as a reference.
If you have experience with Django, much of this will be familiar, but If you have experience with Django, much of this will be familiar, but
you may want to read about how REST requests are dispatched, and how you may want to read about how REST requests are dispatched, and how
request authentication works. request authentication works.
This document supplements the [new feature tutorial](../tutorials/new-feature-tutorial.md) This document supplements the [new feature tutorial](new-feature-tutorial.md)
and the [testing](../testing/testing.md) and the [testing](../testing/testing.md)
documentation. documentation.