2017-07-28 03:00:53 +02:00
|
|
|
# Management commands
|
|
|
|
|
|
|
|
Zulip has a number of [Django management commands][django-docs] that
|
|
|
|
live under `{zerver,zilencer,analytics}/management/commands/`.
|
|
|
|
|
|
|
|
If you need some Python code to run with a Zulip context (access to
|
|
|
|
the database, etc.) in a script, it should probably go in a management
|
2021-08-20 21:53:28 +02:00
|
|
|
command. The key thing distinguishing these from production scripts
|
2017-07-28 03:00:53 +02:00
|
|
|
(`scripts/`) and development scripts (`tools/`) is that management
|
|
|
|
commands can access the database.
|
|
|
|
|
|
|
|
While Zulip takes advantage of built-in Django management commands for
|
2017-07-29 01:12:10 +02:00
|
|
|
things like managing Django migrations, we also have dozens that we've
|
|
|
|
written for a range of purposes:
|
2017-07-28 03:00:53 +02:00
|
|
|
|
2024-07-04 12:33:43 +02:00
|
|
|
- Cron jobs to do regular updates, e.g., `update_analytics_counts.py`,
|
2017-07-28 03:00:53 +02:00
|
|
|
`sync_ldap_user_data`, etc.
|
2021-08-20 21:45:39 +02:00
|
|
|
- Useful parts of provisioning or upgrading a Zulip development
|
2024-07-04 12:33:43 +02:00
|
|
|
environment or server, e.g., `makemessages`, `compilemessages`,
|
2017-07-28 03:00:53 +02:00
|
|
|
`populate_db`, `fill_memcached_caches`, etc.
|
2021-08-20 21:45:39 +02:00
|
|
|
- The actual scripts run by supervisord to run the persistent
|
2024-07-04 12:33:43 +02:00
|
|
|
processes in a Zulip server, e.g., `runtornado` and `process_queue`.
|
2021-08-20 21:45:39 +02:00
|
|
|
- For a sysadmin to verify a Zulip server's configuration during
|
2024-07-04 12:33:43 +02:00
|
|
|
installation, e.g., `checkconfig`, `send_test_email`.
|
2021-08-20 21:45:39 +02:00
|
|
|
- As the interface for doing those rare operations that don't have a
|
2024-07-04 12:33:43 +02:00
|
|
|
UI yet, e.g., `deactivate_realm`, `reactivate_realm`,
|
2017-07-28 03:00:53 +02:00
|
|
|
`change_user_email` (for the case where the user doesn't control the
|
|
|
|
old email address).
|
2021-08-20 21:45:39 +02:00
|
|
|
- For a sysadmin to easily interact with and script common possible
|
2017-07-28 03:00:53 +02:00
|
|
|
changes they might want to make to the database on a Zulip server.
|
2024-07-04 12:33:43 +02:00
|
|
|
E.g., `send_password_reset_email`, `export`, `purge_queue`.
|
2017-07-28 03:00:53 +02:00
|
|
|
|
|
|
|
## Writing management commands
|
|
|
|
|
|
|
|
It's generally pretty easy to template off an existing management
|
2021-08-20 21:53:28 +02:00
|
|
|
command to write a new one. Some good examples are
|
|
|
|
`change_user_email` and `deactivate_realm`. The Django documentation
|
2017-07-28 03:00:53 +02:00
|
|
|
is good, but we have a few pieces advice specific to the Zulip
|
|
|
|
project.
|
|
|
|
|
2024-05-24 15:55:37 +02:00
|
|
|
- Inherit from the `ZulipBaseCommand` class in
|
|
|
|
`zerver/lib/management.py`; this will add some helpful general
|
|
|
|
flags, as well as tools for adding and parsing `--realm` and
|
|
|
|
`--user` flags, so you don't need to write the tedious code of
|
|
|
|
looking those objects up. This is especially important for users,
|
|
|
|
since the library handles the issues around looking up users by
|
|
|
|
email well (if there's a unique user with that email, just modify it
|
|
|
|
without requiring the user to specify the realm as well, but if
|
|
|
|
there's a collision, throw a nice error).
|
2021-08-20 21:45:39 +02:00
|
|
|
- Avoid writing a lot of code in management commands; management
|
2017-07-29 01:12:10 +02:00
|
|
|
commands are annoying to unit test, and thus easier to maintain if
|
|
|
|
all the interesting logic is in a nice function that is unit tested
|
2021-08-20 21:53:28 +02:00
|
|
|
(and ideally, also used in Zulip's existing code). Look for code in
|
|
|
|
`zerver/lib/` that already does what you need. For most actions,
|
2017-07-28 03:00:53 +02:00
|
|
|
you can just call a `do_change_foo` type function from
|
2022-04-14 00:48:36 +02:00
|
|
|
`zerver/actions/` to do all the work; this is usually far
|
2021-04-29 19:06:52 +02:00
|
|
|
better than manipulating the database directly, since the library
|
2017-07-28 03:00:53 +02:00
|
|
|
functions used by the UI are maintained to correctly live-update the
|
|
|
|
UI if needed.
|
|
|
|
|
2021-04-29 19:06:52 +02:00
|
|
|
Management commands are essentially independent Python scripts with
|
|
|
|
access to the Zulip server's database and libraries; so you don't need
|
|
|
|
to do anything special like restart the server when iteratively
|
|
|
|
testing one, even if testing in a Zulip production environment where
|
|
|
|
the server doesn't normally restart whenever a file is edited.
|
|
|
|
|
2024-05-24 16:57:31 +02:00
|
|
|
[django-docs]: https://docs.djangoproject.com/en/5.0/howto/custom-management-commands/
|