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

123 lines
5.1 KiB
Markdown
Raw Normal View History

docs: Make headings consistent and use the imperative.
2016-08-18 02:51:04 +02:00
# Customize Zulip
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
Once you've got Zulip setup, you'll likely want to configure it the
docs: Document how to make settings changes take effect. The page at https://zulip.org/server.html reminds me that we didn't have clear documentation of this point where we discuss configuring the server.
2017-07-28 03:51:22 +02:00
way you like.
## Making changes
Most configuration can be done by a realm administrator, on the web.
For those settings, see [the documentation for realm
administrators][realm-admin-docs].
docs: Highlight getting started guide more strongly.
2017-06-08 22:28:51 +02:00
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
docs: Document how to make settings changes take effect. The page at https://zulip.org/server.html reminds me that we didn't have clear documentation of this point where we discuss configuring the server.
2017-07-28 03:51:22 +02:00
This page discusses additional configuration that a system
administrator can do. To change any of the following settings, edit
the `/etc/zulip/settings.py` file on your Zulip server, and then
restart the server with the following command:
```
docs: Fix missing quotes in `su zulip -c` documentation. This fixes an actual user-facing issue in our mobile push notifications documentation (where we were incorrectly failing to quote the argument to `./manage.py register_server` making it not work), as well as preventing future similar issues from occurring again via a linter rule.
2018-11-30 21:08:25 +01:00
su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
docs: Document how to make settings changes take effect. The page at https://zulip.org/server.html reminds me that we didn't have clear documentation of this point where we discuss configuring the server.
2017-07-28 03:51:22 +02:00
```
## Specific settings
Enable EmailAuthBackend by default to simplify a production install. This should save a step from the installation process in the common case.
2017-06-09 05:59:07 +02:00
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
### Domain and Email settings
`EXTERNAL_HOST`: the user-accessible domain name for your Zulip
installation (i.e., what users will type in their web browser). This
should of course match the DNS name you configured to point to your
server and for which you configured SSL certificates. If you passed
`--hostname` to the installer, this will be prefilled with that value.
Enable EmailAuthBackend by default to simplify a production install. This should save a step from the installation process in the common case.
2017-06-09 05:59:07 +02:00
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
`ZULIP_ADMINISTRATOR`: the email address of the person or team
maintaining this installation and who will get support and error
emails. If you passed `--email` to the installer, this will be
prefilled with that value.
### Authentication Backends
Enable EmailAuthBackend by default to simplify a production install. This should save a step from the installation process in the common case.
2017-06-09 05:59:07 +02:00
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
`AUTHENTICATION_BACKENDS`: Zulip supports a wide range of popular
options for authenticating users to your server, including Google
Auth, GitHub Auth, LDAP, REMOTE_USER, and more. Note, however, that
the default (email) backend must be used when creating a new
organization.
If you want an additional or different authentication backend, you
will need to uncomment one or more and then do any additional
configuration required for that backend as documented in the
`settings.py` file. See the
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[section on Authentication](../production/authentication-methods.md) for more
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
detail on the available authentication backends and how to configure
them.
Enable EmailAuthBackend by default to simplify a production install. This should save a step from the installation process in the common case.
2017-06-09 05:59:07 +02:00
docs: Document how to make settings changes take effect. The page at https://zulip.org/server.html reminds me that we didn't have clear documentation of this point where we discuss configuring the server.
2017-07-28 03:51:22 +02:00
### Mobile and desktop apps
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
The Zulip apps expect to be talking to to servers with a properly
signed SSL certificate, in most cases and will not accept a
self-signed certificate. You should get a proper SSL certificate
before testing the apps.
Because of how Google and Apple have architected the security model of
their push notification protocols, the Zulip mobile apps for
[iOS](https://itunes.apple.com/us/app/zulip/id1203036395) and
mobile: Update docs and portico URLs to point to new Android app.
2017-10-28 21:49:12 +02:00
[Android](https://play.google.com/store/apps/details?id=com.zulipmobile)
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
can only receive push notifications from a single Zulip server. We
have configured that server to be `push.zulipchat.com`, and offer a
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[push notification forwarding service](mobile-push-notifications.md) that
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
forwards push notifications through our servers to mobile devices.
Read the linked documentation for instructions on how to register for
and configure this service.
By the end of summer 2017, all of the Zulip apps will have full
support for multiple accounts, potentially on different Zulip servers,
with a convenient UI for switching between them.
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
Capitalize s in Terms of service. A few strings used `Terms of service` instead of `Terms of Service`. This change makes the latter form consistent over the repo.
2017-09-05 10:14:02 +02:00
### Terms of Service and Privacy policy
Add default response for `terms` and `privacy` endpoints. - Add setting for `privacy policy` template defining. - Configure default templates for `privacy policy` and `terms of service` pages. - Add route for privacy page. - Remove condition for showing `privacy` and `terms` pages. - Add `privacy_policy` setting to context processor. - Add documentaion part for `privacy` and `terms` templates configuration. - Add tests. Fixes #3686.
2017-04-10 12:55:43 +02:00
Zulip allows you to configure your server's Terms of Service and
Privacy Policy pages (`/terms` and `/privacy`, respectively). You can
use the `TERMS_OF_SERVICE` and `PRIVACY_POLICY` settings to configure
the path to your server's policies. The syntax is Markdown (with
support for included HTML). A good approach is to use paths like
`/etc/zulip/terms.md`, so that it's easy to back up your policy
configuration along with your other Zulip server configuration.
docs: Document how to make settings changes take effect. The page at https://zulip.org/server.html reminds me that we didn't have clear documentation of this point where we discuss configuring the server.
2017-07-28 03:51:22 +02:00
### Miscellaneous server settings
docs: Improve navigation of prod-customize page. - Add headings for each of the six major sections: integrations, streams and topics, notification settings, mobile and desktop apps, other great features, and enjoy your Zulip installation. - Add links to each of these sections to top of page, with first and most important four formatted as a list.
2016-08-09 23:31:22 +02:00
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
Zulip has dozens of settings documented in the comments in
`/etc/zulip/settings.py`; you can review
[the latest version of the settings.py template][settings-py-template]
if you've deleted the comments or want to check if new settings have
been added in more recent versions of Zulip.
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
Since Zulip's settings file is a Python script, there are a number of
other things that one can configure that are not documented; ask on
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[chat.zulip.org](../contributing/chat-zulip-org.md)
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
if there's something you'd like to do but can't figure out how to.
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
[settings-py-template]: https://github.com/zulip/zulip/blob/master/zproject/prod_settings_template.py
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
docs: Mention a few highlights from settings.py.
2017-08-16 02:16:29 +02:00
Some popular settings in `/etc/zulip/settings.py` include:
* The Twitter integration, which provides pretty inline previews of
tweets.
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
* The [email gateway](../production/email-gateway.md), which lets
docs: Move prose email mirror instructions out of settings template. This should make it easier to understand the documentation.
2019-07-05 17:33:48 +02:00
users send emails into Zulip.
docs: Mention a few highlights from settings.py.
2017-08-16 02:16:29 +02:00
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
## Zulip announcement list
docs: Improve navigation of prod-customize page. - Add headings for each of the six major sections: integrations, streams and topics, notification settings, mobile and desktop apps, other great features, and enjoy your Zulip installation. - Add links to each of these sections to top of page, with first and most important four formatted as a list.
2016-08-09 23:31:22 +02:00
docs: Document the push notification forwarding service.
2017-05-16 22:28:15 +02:00
If you haven't already, subscribe to the
[zulip-announce](https://groups.google.com/forum/#!forum/zulip-announce)
list so that you can receive important announces like new Zulip
releases or major changes to the app ecosystem..
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
docs: Update customization docs slightly for Zulip 1.5. There's more we'll want to do here now that we have /help/, but this is a good start.
2017-02-03 21:56:33 +01:00
## Enjoy your Zulip installation!
docs: Improve navigation of prod-customize page. - Add headings for each of the six major sections: integrations, streams and topics, notification settings, mobile and desktop apps, other great features, and enjoy your Zulip installation. - Add links to each of these sections to top of page, with first and most important four formatted as a list.
2016-08-09 23:31:22 +02:00
docs: Update customization docs slightly for Zulip 1.5. There's more we'll want to do here now that we have /help/, but this is a good start.
2017-02-03 21:56:33 +01:00
If you discover things that you wish had been documented, please
contribute documentation suggestions either via a GitHub issue or pull
request; we love even small contributions, and we'd love to make the
Zulip documentation cover everything anyone might want to know about
running Zulip in production.
Move prod customization guide to new page.
2016-07-12 22:43:00 +02:00
Next: [Maintaining and upgrading Zulip in
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
production](../production/maintain-secure-upgrade.md).