mirror of https://github.com/zulip/zulip.git
86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# Realms in Zulip
|
|
|
|
Zulip allows multiple *realms* to be hosted on a single instance.
|
|
Realms are the Zulip codebases's internal name for what we refer to in
|
|
user documentation as an organization (the name "realm" comes from
|
|
[Kerberos](https://web.mit.edu/kerberos/)).
|
|
|
|
## Creating Realms
|
|
|
|
There are two main methods for creating realms.
|
|
|
|
* Using unique link generator
|
|
* Enabling open realm creation
|
|
|
|
#### Using Unique Link Generator
|
|
|
|
```bash
|
|
./manage.py generate_realm_creation_link
|
|
```
|
|
|
|
The above command will ouput a URL which can be used for creating a
|
|
new realm and an administrator user for that realm. The link expires
|
|
after the creation of the realm. The link also expires if not used
|
|
within 7 days. The expiration period can be changed by modifying
|
|
`REALM_CREATION_LINK_VALIDITY_DAYS` in settings.py.
|
|
|
|
### Enabling Open Realm Creation
|
|
|
|
If you want anyone to be able to create new realms on your server, you
|
|
can enable Open Realm Creation. This will add a **Create new
|
|
organization** link to your Zulip homepage footer, and anyone can
|
|
create a new realm by visiting this link (**/create_realm**). This
|
|
feature is disabled by default in production instances, and can be
|
|
enabled by setting `OPEN_REALM_CREATION = True` in settings.py.
|
|
|
|
## Subdomains
|
|
|
|
A reasonable way to deploy a multi-realm Zulip server in production is
|
|
to give each realm a unique subdomain. For example if the Zulip
|
|
instance is hosted at zulip.example.com and the subdomain of your
|
|
organization is acme you can use acme.zulip.example.com for accessing
|
|
the organization. This subdomain feature is not enabled by default,
|
|
since it requires additional DNS configuration. You can enable
|
|
subdomains by setting the value of `REALMS_HAVE_SUBDOMAINS` to True in
|
|
settings.py. For subdomains to work properly, you also have to change
|
|
your DNS records so that the subdomains point to your Zulip
|
|
installation IP. An `A` record with host name value `*` pointing to
|
|
your IP should do the job.
|
|
|
|
Converting a production Zulip server from not using subdomains to
|
|
using subdomains requires some setup work; contact the Zulip
|
|
development community for help with this.
|
|
|
|
### Working With Subdomains In Development Evironment
|
|
|
|
By default, Linux does not provide a convenient way to use subdomains
|
|
in your local development environment. To solve this problem, we use
|
|
the **zulipdev.com** domain, which has a wildcard A record pointing to
|
|
127.0.0.1. When `REALMS_HAVE_SUBDOMAINS = True` in
|
|
`zproject/dev_settings.py`, you should use zulipdev.com to connect to
|
|
your Zulip development server instead of localhost. The default realm
|
|
with the Shakespeare users has the subdomain `zulip` and can be
|
|
accessed by visiting **zulip.zulipdev.com**.
|
|
|
|
If you are behind a **proxy server**, this method won't work. When you
|
|
make a request to load zulipdev.com in your browser, the proxy server
|
|
will try to get the page on your behalf. Since zulipdev.com points
|
|
to 127.0.0.1 the proxy server is likely to give you a 503 error. The
|
|
workaround is to disable your proxy for `*.zulipdev.com`. The DNS
|
|
lookup should still work even if you disable proxy for
|
|
*.zulipdev.com. If it doesn't you can add zulipdev.com records in
|
|
`/etc/hosts` file. The file should look something like this.
|
|
|
|
```
|
|
127.0.0.1 localhost
|
|
|
|
127.0.0.1 zulipdev.com
|
|
|
|
127.0.0.1 zulip.zulipdev.com
|
|
|
|
127.0.0.1 testsubdomain.zulipdev.com
|
|
```
|
|
|
|
These records are also useful if you want to e.g. run the casper tests
|
|
when you are not connected to the Internet.
|