paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-03 21:43:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Reorganize and refocus section on management commands.

Browse Source
This commit is contained in:
Tim Abbott
2019-11-22 10:46:00 -08:00
parent 5a7b5f1337
commit c9a3e4e872
1 changed files with 72 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,22 +1,43 @@
# Management commands
Zulip has a large library of [Django management
commands](https://docs.djangoproject.com/en/1.8/ref/django-admin/#django-admin-and-manage-py).
To use them, you will want to be logged in as the `zulip` user and for
the purposes of this documentation, we assume the current working
directory is `/home/zulip/deployments/current`.
Sometimes, you need to modify or inspect Zulip data from the command
line. To help with this, Zulip ships with over 100 command-line tools
implemented using the [Django management commands
framework][django-management].
Below, we show several useful examples, but there are more than 100
in total. We recommend skimming the usage docs (or if there are none,
the code) of a management command before using it, since they are
generally less polished and more designed for expert use than the rest
of the Zulip system.
[django-management]: https://docs.djangoproject.com/en/1.11/ref/django-admin/#django-admin-and-manage-py
## Running management commands
Many management commands require the Zulip realm/organization to
interact with as an argument, which you can specify via numeric or
string ID.
Start by logging in as the `zulip` user on the Zulip server. Then run
them as follows:
```
cd /home/zulip/deployments/current
# Start by reading the help
./manage.py <command_name> --help
# Once you've determine this is the command for you, run it!
./manage.py <command_name> <args>
```
A full list of commands is available via `./manage.py help`; you'll
primarily want to use those in the `[zerver]` section as those are the
ones specifically built for Zulip.
As a warning, some of them are designed for specific use cases and may
cause problems if run in other situations. If you're not sure, it's
worth reading the documentation (or the code, usually available at
`zerver/management/commands/`; they're generally very simple programs).
### Accessing an organization's realm ID
Since Zulip supports hosting multiple organizations on a single
server, many management commands require you specify which
organization ("realm") you'd like to modify. Many management commands
require the Zulip realm/organization to interact with as an argument,
which you can specify via numeric or string ID.
You can see all the organizations on your Zulip server using
`./manage.py list_realms`.
@@ -29,14 +50,15 @@ id string_id name
2 Zulip Community
```
(Note that every Zulip server has a special `zulipinternal` realm containing
system-internal bots like `welcome-bot`; you are unlikely to need to
interact with that realm.)
(Note that every Zulip server has a special `zulipinternal` realm
containing system-internal bots like `Notification Bot`; you are
unlikely to ever need to interact with that realm.)
Unless you are
[hosting multiple organizations on your Zulip server](../production/multiple-organizations.md),
your single Zulip organization on the root domain will have the empty
string (`''`) as its `string_id`. So you can run e.g.:
```
zulip@zulip:~$ /home/zulip/deployments/current/manage.py show_admins -r ''
```
@@ -47,72 +69,61 @@ subdomain. E.g. on `it.zulip.example.com`, use
## manage.py shell
If you need to query or edit data directly in the Zulip database, the
best way to do this is with Django's built-in management shell.
You can get an iPython shell with full access to code within the Zulip
project using `manage.py shell`, e.g., you can do the following to
change a user's email address:
```
$ /home/zulip/deployments/current/manage.py shell
$ cd /home/zulip/deployments/current/
$ ./manage.py shell
In [1]: user_profile = get_user_profile_by_email("email@example.com")
In [2]: do_change_user_delivery_email(user_profile, "new_email@example.com")
```
### manage.py dbshell
Any Django tutorial can give you helpful advice on querying and
formatting data from Zulip's tables for inspection.
This will start a postgres shell connected to the Zulip database.
We recommend against directly editing objects and saving them using
Django's `object.save()`. While this will save your changes to the
database, for most objects, in addition to saving the changes to the
database, one may also need to flush caches, notify the apps and open
browser windows, and record the change in Zulip's `RealmAuditLog`
audit history table. For almost any data change you want to do, there
is already a function in `zerver.lib.actions.py` with a name like
`do_change_full_name` that updates that field and notifies clients
correctly.
## Grant administrator access
You can make any user a realm administrator on the command line with
the `knight` management command:
```
./manage.py knight username@example.com -f
```
### Creating API super users with manage.py
If you need to manage the IRC, Jabber, or Zephyr mirrors, you will
need to create API super users. To do this, use `./manage.py knight`
with the `--permission=api_super_user` argument. See the respective
integration scripts for these mirrors (under
[`zulip/integrations/`][integrations-source] in the [Zulip Python API
repo][python-api-repo]) for further detail on these.
[integrations-source]: https://github.com/zulip/python-zulip-api/tree/master/zulip/integrations
[python-api-repo]: https://github.com/zulip/python-zulip-api
### Exporting users and realms with manage.py export
If you need to do an export of a single user or of an entire realm, we
have tools in `management/` that essentially export Zulip data to the
file system.
`export_single_user.py` exports the message history and realm-public
metadata for a single Zulip user (including that user's *received*
messages as well as their sent messages).
A good overview of the process for exporting a single realm when
moving a realm to a new server (without moving a full database dump)
is in
[management/export.py](https://github.com/zulip/zulip/blob/master/zerver/management/commands/export.py). We
recommend you read the comment there for words of wisdom on speed,
what is and is not exported, what will break upon a move to a new
server, and suggested procedure.
For convenience, Zulip automatically import `zerver/models.py` and
`zerver/lib/actions.py` into every management shell; if you need to
access other functions, you'll need to import them yourself.
## Other useful manage.py commands
There are dozens of useful management commands under
`zerver/management/commands/`. We detail a few here:
* `manage.py help`: Lists all available management commands.
* `manage.py send_custom_email`: Can be used to send an email to a set
* `./manage.py help`: Lists all available management commands.
* `./manage.py dbshell`: If you're more comfortable with raw SQL than
Python, this will open a Postgres SQL shell connected to the Zulip
server's database. Beware of changing data; editing data directly
with SQL will often not behave correctly because Postgres doesn't
know to flush Zulip's caches or notify browsers of changes.
* `./manage.py send_custom_email`: Can be used to send an email to a set
of users. The `--help` documents how to run it from a `manage.py
shell` for use with more complex programmatically computed sets of
users.
* `manage.py send_password_reset_email`: Sends password reset email(s)
* `./manage.py send_password_reset_email`: Sends password reset email(s)
to one or more users.
* `manage.py change_user_email`: Change a user's email address.
* `./manage.py change_user_email`: Change a user's email address.
* `./manage.py knight`: Can toggle whether a user is an administrator
(easier done via the UI) or create an API super user bot (with
`--permission=api_super_user`).
* `./manage.py export_single_user` does a limited version of the [main
export tools](../production/export-and-import.md) containing just
the messages accessible by a single user.
All of our management commands have internal documentation available
via `manage.py command_name --help`.