diff --git a/docs/production/management-commands.md b/docs/production/management-commands.md index 6ded741f8a..cfca8c9842 100644 --- a/docs/production/management-commands.md +++ b/docs/production/management-commands.md @@ -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 --help + +# Once you've determine this is the command for you, run it! +./manage.py +``` + +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`.