Doc - add CLI

This commit is contained in:
Sam 2022-04-24 13:16:10 +02:00
parent fa399d39cc
commit 6f9535d75a
4 changed files with 101 additions and 13 deletions

67
docsrc/source/cli.rst Normal file
View File

@ -0,0 +1,67 @@
Command line interface
######################
A command line interface (CLI) is available to manage database and users.
.. code-block:: bash
$ ftcli
Usage: ftcli [OPTIONS] COMMAND [ARGS]...
FitTrackee Command Line Interface
Options:
--help Show this message and exit.
Commands:
db Manage database.
users Manage users.
.. warning::
| The following commands are now deprecated and will be removed in a next version:
| - ``fittrackee_set_admin``
| - ``fittrackee_upgrade_db``
Database
~~~~~~~~
``ftcli db upgrade``
""""""""""""""""""""
.. versionadded:: 0.6.5
Apply migrations.
``ftcli db drop``
"""""""""""""""""
.. versionadded:: 0.6.5
Empty database and delete uploaded files, only on development environments.
Users
~~~~~
``ftcli users update``
""""""""""""""""""""""
.. versionadded:: 0.6.5
Modify a user account (admin rights, active status, email and password).
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Options
- Description
* - ``--set-admin BOOLEAN``
- Add/remove admin rights (when adding admin rights, it also activates user account if not active).
* - ``--activate``
- Activate user account.
* - ``--reset-password``
- Reset user password (a new password will be displayed).
* - ``--update-email EMAIL``
- Update user email.

View File

@ -60,10 +60,11 @@ Workouts
Account & preferences Account & preferences
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
- A user can create, update and deleted his account. - A user can create, update and deleted his account.
- After registration, the user account is inactive and an email with confirmation instructions is sent to activate it. A user with an inactive account cannot log in. (*new in 0.6.0*) - After registration, the user account is inactive and an email with confirmation instructions is sent to activate it.
A user with an inactive account cannot log in. (*new in 0.6.0*)
.. note:: .. note::
The command line to add admin rights activates the account if it is inactive. In case email sending is not configured, a `command line <cli.html#ftcli-users-update>`__ allows to activate users account.
- A user can set language, timezone and first day of week. - A user can set language, timezone and first day of week.
- A user can reset his password (*new in 0.3.0*) - A user can reset his password (*new in 0.3.0*)
@ -97,6 +98,9 @@ Administration
.. warning:: .. warning::
Updating server configuration may be necessary to handle large files (like `nginx <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_ for instance). Updating server configuration may be necessary to handle large files (like `nginx <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_ for instance).
.. note::
If email sending is disabled, a warning is displayed.
- **Users** - **Users**

View File

@ -34,6 +34,7 @@ Table of contents
features features
installation installation
cli
api/index api/index
troubleshooting/index troubleshooting/index
changelog changelog

View File

@ -22,9 +22,8 @@ Prerequisites
- Python 3.7+ - Python 3.7+
- PostgreSQL database (10+) - PostgreSQL database (10+)
- SMTP provider - SMTP provider and Redis for task queue (if email sending is enabled)
- Redis for task queue (to send emails) - API key from `Dark Sky <https://darksky.net/dev>`__ (not mandatory)
- API key from `Dark Sky <https://darksky.net/dev>`__ [not mandatory]
- `Poetry <https://poetry.eustace.io>`__ (for installation from sources only) - `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
- `Yarn <https://yarnpkg.com>`__ (for development only) - `Yarn <https://yarnpkg.com>`__ (for development only)
- Docker and Docker Compose (for development or evaluation purposes) - Docker and Docker Compose (for development or evaluation purposes)
@ -133,6 +132,13 @@ deployment method.
Email URL with credentials, see `Emails <installation.html#emails>`__. Email URL with credentials, see `Emails <installation.html#emails>`__.
.. versionchanged:: 0.6.5
:default: empty string
.. danger::
If the email URL is empty, email sending will be disabled.
.. warning:: .. warning::
If the email URL is invalid, the application may not start. If the email URL is invalid, the application may not start.
@ -214,7 +220,7 @@ To send emails, a valid ``EMAIL_URL`` must be provided:
| - If the email URL is invalid, the application may not start. | - If the email URL is invalid, the application may not start.
| - Sending emails with Office365 may not work if SMTP auth is disabled. | - Sending emails with Office365 may not work if SMTP auth is disabled.
.. versionadded:: 0.5.3 .. versionchanged:: 0.5.3
| Credentials can be omitted: ``smtp://smtp.example.com:25``. | Credentials can be omitted: ``smtp://smtp.example.com:25``.
| If ``:<port>`` is omitted, the port defaults to 25. | If ``:<port>`` is omitted, the port defaults to 25.
@ -229,6 +235,11 @@ Emails sent by FitTrackee are:
- email change (to old and new email adresses) - email change (to old and new email adresses)
- password change - password change
.. versionchanged:: 0.6.5
| For single-user instance, it is possible to disable email sending with an empty ``EMAIL_URL`` (in this case, no need to start dramatiq workers).
| A `CLI <cli.html#ftcli-users-update>`__ is available to activate account and modify email and password.
Map tile server Map tile server
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
@ -288,7 +299,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the
.. code-block:: bash .. code-block:: bash
$ fittrackee_upgrade_db $ ftcli db upgrade
- Start the application - Start the application
@ -296,7 +307,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the
$ fittrackee $ fittrackee
- Start task queue workers - Start task queue workers if email sending is enabled.
.. code-block:: bash .. code-block:: bash
@ -311,7 +322,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the
.. code:: bash .. code:: bash
$ fittrackee_set_admin <username> $ ftcli users update <username> --set-admin true
.. note:: .. note::
If the user account is inactive, it activates it. If the user account is inactive, it activates it.
@ -373,7 +384,7 @@ Dev environment
.. code:: bash .. code:: bash
$ make set-admin USERNAME=<username> $ make user-set-admin USERNAME=<username>
.. note:: .. note::
If the user account is inactive, it activates it. If the user account is inactive, it activates it.
@ -415,13 +426,16 @@ Production environment
$ make run $ make run
.. note::
If email sending is disabled: ``$ make run-server``
- Open http://localhost:5000 and register - Open http://localhost:5000 and register
- To set admin rights to the newly created account, use the following command line: - To set admin rights to the newly created account, use the following command line:
.. code:: bash .. code:: bash
$ make set-admin USERNAME=<username> $ make user-set-admin USERNAME=<username>
.. note:: .. note::
If the user account is inactive, it activates it. If the user account is inactive, it activates it.
@ -457,9 +471,9 @@ From PyPI
.. code-block:: bash .. code-block:: bash
$ fittrackee_upgrade_db $ ftcli db upgrade
- Restart the application and task queue workers. - Restart the application and task queue workers (if email sending is enabled).
From sources From sources
@ -536,6 +550,8 @@ Prod environment
$ make run $ make run
.. note::
If email sending is disabled: ``$ make run-server``
Deployment Deployment
~~~~~~~~~~ ~~~~~~~~~~