mirror of
https://github.com/zulip/zulip.git
synced 2025-11-02 13:03:29 +00:00
docs: Rewrite server configuration page.
- Restructure the introductory content to be more focused on the overview. - The bottom content was a stale duplicate of the bottom of the installer page, dating from when this was a required step after running the installer. - Most of the longer-form sections were duplicates of sections of either the installer page or the introductions of dedicated pages on the topic. Remove these in favor of new entries in the popular settings area. - Mention storage as a popular setting to configure. - Remove deleted Twitter integration from popular settings list.
This commit is contained in:
Tim Abbott
@@ -53,7 +53,7 @@ server as follows:
|
||||
|
||||
[update-settings-docs]: ../production/upgrade.md#updating-settingspy-inline-documentation
|
||||
|
||||
1. [Restart your Zulip server](settings.md#making-changes) so that
|
||||
1. [Restart your Zulip server](settings.md#changing-server-settings) so that
|
||||
your configuration changes take effect.
|
||||
|
||||
1. Run the registration command. If you installed Zulip directly on the server
|
||||
@@ -411,7 +411,7 @@ registration.
|
||||
`ZULIP_SERVICE_PUSH_NOTIFICATIONS = True` line
|
||||
in your `/etc/zulip/settings.py` file (i.e., add `# ` at the
|
||||
start of the line), and [restart your Zulip
|
||||
server](settings.md#making-changes).
|
||||
server](settings.md#changing-server-settings).
|
||||
|
||||
If you ever need to reactivate your server's registration, [contact Zulip
|
||||
support](https://zulip.com/help/contact-support).
|
||||
@@ -421,7 +421,7 @@ support](https://zulip.com/help/contact-support).
|
||||
You can temporarily stop using the Mobile Push Notification Service. Comment out
|
||||
the `PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line in your
|
||||
`/etc/zulip/settings.py` file (i.e., add `# ` at the start of the line), and
|
||||
[restart your Zulip server](settings.md#making-changes). This approach makes it
|
||||
[restart your Zulip server](settings.md#changing-server-settings). This approach makes it
|
||||
easy to start using the service again by uncommenting the same line.
|
||||
|
||||
## Sending push notifications directly from your server
|
||||
|
||||
@@ -1,137 +1,80 @@
|
||||
# Server configuration
|
||||
|
||||
Once you've got Zulip set up, you'll likely want to configure it the
|
||||
way you like.
|
||||
This page explains the configuration options in `/etc/zulip/settings.py`, the
|
||||
main configuration file used by system administrators to configure their Zulip
|
||||
server.
|
||||
|
||||
## 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].
|
||||
[Organization administrators][user-roles] can also [configure][realm-admin-docs]
|
||||
many options for a Zulip organization from the web or desktop app. See [system
|
||||
and deployment configuration documentation](system-configuration.md) for advanced
|
||||
configuration of the various services that make up a complete Zulip installation
|
||||
(`/etc/zulip/zulip.conf`).
|
||||
|
||||
[realm-admin-docs]: https://zulip.com/help/moving-to-zulip
|
||||
[user-roles]: https://zulip.com/help/user-roles
|
||||
|
||||
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:
|
||||
## Server settings overview
|
||||
|
||||
The Zulip server self-documents more than a hundred settings in the
|
||||
organized comments in `/etc/zulip/settings.py`. You can read [the
|
||||
latest version of the settings.py template][settings-py-template] in a
|
||||
browser.
|
||||
|
||||
[settings-py-template]: https://github.com/zulip/zulip/blob/main/zproject/prod_settings_template.py
|
||||
|
||||
Important settings in `/etc/zulip/settings.py` include:
|
||||
|
||||
- The mandatory `EXTERNAL_HOST` and `ZULIP_ADMINISTRATOR` settings,
|
||||
which are prefilled by the [installer](install.md).
|
||||
- [Authentication methods](authentication-methods.md), including data
|
||||
synchronization options like LDAP and SCIM.
|
||||
- The [email gateway](email-gateway.md), which lets
|
||||
users send emails into Zulip.
|
||||
- [Video and voice call integrations](video-calls.md).
|
||||
- How the server should store [uploaded files](upload-backends.md).
|
||||
|
||||
## Changing server settings
|
||||
|
||||
To change any of the settings in `/etc/zulip/settings.py`, modify and save the
|
||||
file on your Zulip server, and restart the server with the following command:
|
||||
|
||||
```bash
|
||||
su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
|
||||
```
|
||||
|
||||
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], and if you've upgraded
|
||||
from an old version of Zulip, we recommend [carefully updating your
|
||||
`/etc/zulip/settings.py`][update-settings-docs] to fold in the inline
|
||||
comment documentation for new configuration settings after upgrading
|
||||
to each new major release.
|
||||
If you have questions about how to configure your server, best-effort community
|
||||
support is available in the [Zulip development community][chat-zulip-org].
|
||||
Contact [sales@zulip.com](mailto:sales@zulip.com) to learn about paid support
|
||||
options.
|
||||
|
||||
[update-settings-docs]: upgrade.md#updating-settingspy-inline-documentation
|
||||
[settings-py-template]: https://github.com/zulip/zulip/blob/main/zproject/prod_settings_template.py
|
||||
[chat-zulip-org]: https://zulip.com/development-community/
|
||||
|
||||
Since Zulip’s settings file is a Python script, there are a number of
|
||||
other things that one can configure that are documented in
|
||||
[System and deployment configuration](system-configuration.md).
|
||||
Otherwise, ask in [the Zulip development community](https://zulip.com/development-community/)
|
||||
if there’s something you’d like to do but can’t figure out how to.
|
||||
## Custom Terms of Service and Privacy policy
|
||||
|
||||
## Specific settings
|
||||
:::{important}
|
||||
|
||||
### Domain and email settings
|
||||
If you are using this feature, please make sure the name of your organization
|
||||
appears prominently in all documents, to avoid confusion with policies for Zulip
|
||||
Cloud.
|
||||
|
||||
`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.
|
||||
:::
|
||||
|
||||
`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.
|
||||
Zulip lets you configure your server's Terms of Service and
|
||||
Privacy Policy pages.
|
||||
|
||||
### Authentication backends
|
||||
Policy documents are stored as Markdown files in the configured
|
||||
`POLICIES_DIRECTORY`. We recommend using `/etc/zulip/policies` as the directory,
|
||||
so that your policies are naturally backed up with the server's other
|
||||
configurations.
|
||||
|
||||
`AUTHENTICATION_BACKENDS`: Zulip supports a wide range of popular
|
||||
options for authenticating users to your server, including Google
|
||||
auth, GitHub auth, LDAP, SAML, REMOTE_USER, and more.
|
||||
To provide Terms of Service and a Privacy Policy for your users, place Markdown
|
||||
files named `terms.md` and `privacy.md` in the configured directory, and set
|
||||
`TERMS_OF_SERVICE_VERSION` to `1.0` to enable this feature.
|
||||
|
||||
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
|
||||
[section on authentication](authentication-methods.md) for more
|
||||
detail on the available authentication backends and how to configure
|
||||
them.
|
||||
|
||||
### Mobile and desktop apps
|
||||
|
||||
The Zulip apps expect to be talking 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
|
||||
[Android](https://play.google.com/store/apps/details?id=com.zulipmobile)
|
||||
can only receive push notifications from a single Zulip server. We
|
||||
have configured that server to be `push.zulipchat.com`, and offer a
|
||||
[push notification forwarding service](mobile-push-notifications.md) that
|
||||
forwards push notifications through our servers to mobile devices.
|
||||
Read the linked documentation for instructions on how to register for
|
||||
and configure this service.
|
||||
|
||||
### Terms of Service and Privacy policy
|
||||
|
||||
Zulip allows you to configure your server's Terms of Service and
|
||||
Privacy Policy pages (`/terms` and `/privacy`, respectively).
|
||||
|
||||
You can configure this using the `POLICIES_DIRECTORY` setting. We
|
||||
recommend using `/etc/zulip/policies`, so that your policies are
|
||||
naturally backed up with the server's other configuration. Just place
|
||||
Markdown files named `terms.md` and `privacy.md` in that directory,
|
||||
and set `TERMS_OF_SERVICE_VERSION` to `1.0` to enable this feature.
|
||||
|
||||
You can place additional files in this directory to document
|
||||
additional policies; if you do so, you may want to:
|
||||
You can put additional files in the same directory to document other
|
||||
policies; if you do so, you may want to:
|
||||
|
||||
- Create a Markdown file `sidebar_index.md` listing the pages in your
|
||||
policies site; this generates the policies site navigation.
|
||||
- Create a Markdown file `missing.md` with custom content for 404s in
|
||||
this directory.
|
||||
|
||||
Please make clear in these pages what organization is hosting your
|
||||
Zulip server, so that nobody could be confused that your policies are
|
||||
the policies for Zulip Cloud.
|
||||
|
||||
### Miscellaneous server settings
|
||||
|
||||
Some popular settings in `/etc/zulip/settings.py` include:
|
||||
|
||||
- The Twitter integration, which provides pretty inline previews of
|
||||
tweets.
|
||||
- The [email gateway](email-gateway.md), which lets
|
||||
users send emails into Zulip.
|
||||
- The [Video call integrations](video-calls.md).
|
||||
|
||||
## Zulip announcement list
|
||||
|
||||
Subscribe to the [Zulip announcements email
|
||||
list](https://groups.google.com/g/zulip-announce) for server administrators, if
|
||||
you have not done so already. This extremely low-traffic list is for important
|
||||
announcements, including [new releases](../overview/release-lifecycle.md) and
|
||||
security issues.
|
||||
|
||||
## Enjoy your Zulip installation!
|
||||
|
||||
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.
|
||||
|
||||
Next: [Backups, export and import](export-and-import.md) and
|
||||
[upgrading](upgrade.md) Zulip in production.
|
||||
|
||||
Reference in New Issue
Block a user