¶ Note:
In Zulip, the terms realms and organizations are synonyms, except for an internal realm used exclusively for bots. In this document, these terms will be used interchangeably.
All organizations in Zulip must be subdomains of a main host, which is specified in the EXTERNAL_HOST variable in /etc/zulip/settings.py. Therefore, it is necessary to create at least one new DNS record, typically a subdomain under the main host. For example, in our case, a subdomain like org1.zulip.coopdevs.org is created under zulip.coopdevs.org.
If you want to use a domain that does not belong to the main host, you will need to create a new DNS record that points to the machine’s IP address.
In this second case, additional steps are required:
ALLOWED_HOSTS setting in the settings.py file.For example:
zulip.coopdevs.org is the main host.org1.zulip.coopdevs.org would be a subdomain for a realm.zulip.devs.coop could be a separate domain for an organization.To issue SSL certificates for the new domains, run the following command:
sudo -s
/home/zulip/deployments/current/scripts/setup/setup-certbot --email=<certbot_email> zulip.coopdevs.org org1.zulip.coopdevs.org zulip.devs.coop
Replace <certbot_email> with your email address for Certbot notifications.
Once the domains are correctly configured and the SSL certificates are issued, you can create a new organization using the generate_realm_creation_link command:
sudo -s
cd /home/zulip/deployments/current/
su zulip -c './manage.py generate_realm_creation_link'
This command will output a one-time link that you can use to create the new organization. You’ll need to specify:
org1.zulip.coopdevs.org).After completing this step, verify that the realm was created by listing all existing realms:
sudo -s
cd /home/zulip/deployments/current/
su zulip -c './manage.py list_realms'
This will display the realm’s name and ID.
To associate a custom domain (e.g., zulip.devs.coop) with the new organization, follow these steps:
Use the list_realms command to identify the name of the realm associated with the new organization.
ALLOWED_HOSTSIn /etc/zulip/settings.py, add or update the ALLOWED_HOSTS variable to include the new domain:
ALLOWED_HOSTS = ["zulip.devs.coop"]
Add or update the REALM_HOSTS variable in the same file. This variable is a Python dictionary where the keys are the realm’s subdomains, and the values are the corresponding custom domains:
REALM_HOSTS = {
"org1": "zulip.devs.coop",
}
After completing these configurations: