From 6f9535d75aa28b5347146d13004cf119d31d2a45 Mon Sep 17 00:00:00 2001 From: Sam Date: Sun, 24 Apr 2022 13:16:10 +0200 Subject: [PATCH] Doc - add CLI --- docsrc/source/cli.rst | 67 ++++++++++++++++++++++++++++++++++ docsrc/source/features.rst | 8 +++- docsrc/source/index.rst | 1 + docsrc/source/installation.rst | 38 +++++++++++++------ 4 files changed, 101 insertions(+), 13 deletions(-) create mode 100644 docsrc/source/cli.rst diff --git a/docsrc/source/cli.rst b/docsrc/source/cli.rst new file mode 100644 index 00000000..b65e4816 --- /dev/null +++ b/docsrc/source/cli.rst @@ -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. diff --git a/docsrc/source/features.rst b/docsrc/source/features.rst index e5fd1667..3d052839 100644 --- a/docsrc/source/features.rst +++ b/docsrc/source/features.rst @@ -60,10 +60,11 @@ Workouts Account & preferences ^^^^^^^^^^^^^^^^^^^^^ - 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:: - The command line to add admin rights activates the account if it is inactive. + In case email sending is not configured, a `command line `__ allows to activate users account. - A user can set language, timezone and first day of week. - A user can reset his password (*new in 0.3.0*) @@ -97,6 +98,9 @@ Administration .. warning:: Updating server configuration may be necessary to handle large files (like `nginx `_ for instance). + .. note:: + If email sending is disabled, a warning is displayed. + - **Users** diff --git a/docsrc/source/index.rst b/docsrc/source/index.rst index 5df6bcbf..95a66056 100644 --- a/docsrc/source/index.rst +++ b/docsrc/source/index.rst @@ -34,6 +34,7 @@ Table of contents features installation + cli api/index troubleshooting/index changelog diff --git a/docsrc/source/installation.rst b/docsrc/source/installation.rst index 56e687cf..e42c11f1 100644 --- a/docsrc/source/installation.rst +++ b/docsrc/source/installation.rst @@ -22,9 +22,8 @@ Prerequisites - Python 3.7+ - PostgreSQL database (10+) -- SMTP provider -- Redis for task queue (to send emails) -- API key from `Dark Sky `__ [not mandatory] +- SMTP provider and Redis for task queue (if email sending is enabled) +- API key from `Dark Sky `__ (not mandatory) - `Poetry `__ (for installation from sources only) - `Yarn `__ (for development only) - Docker and Docker Compose (for development or evaluation purposes) @@ -133,6 +132,13 @@ deployment method. Email URL with credentials, see `Emails `__. + .. versionchanged:: 0.6.5 + + :default: empty string + + .. danger:: + If the email URL is empty, email sending will be disabled. + .. warning:: 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. | - 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``. | If ``:`` is omitted, the port defaults to 25. @@ -229,6 +235,11 @@ Emails sent by FitTrackee are: - email change (to old and new email adresses) - 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 `__ is available to activate account and modify email and password. + Map tile server ^^^^^^^^^^^^^^^ @@ -288,7 +299,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the .. code-block:: bash - $ fittrackee_upgrade_db + $ ftcli db upgrade - Start the application @@ -296,7 +307,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the $ fittrackee -- Start task queue workers +- Start task queue workers if email sending is enabled. .. code-block:: bash @@ -311,7 +322,7 @@ For instance, copy and update ``.env`` file from ``.env.example`` and source the .. code:: bash - $ fittrackee_set_admin + $ ftcli users update --set-admin true .. note:: If the user account is inactive, it activates it. @@ -373,7 +384,7 @@ Dev environment .. code:: bash - $ make set-admin USERNAME= + $ make user-set-admin USERNAME= .. note:: If the user account is inactive, it activates it. @@ -415,13 +426,16 @@ Production environment $ make run +.. note:: + If email sending is disabled: ``$ make run-server`` + - Open http://localhost:5000 and register - To set admin rights to the newly created account, use the following command line: .. code:: bash - $ make set-admin USERNAME= + $ make user-set-admin USERNAME= .. note:: If the user account is inactive, it activates it. @@ -457,9 +471,9 @@ From PyPI .. 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 @@ -536,6 +550,8 @@ Prod environment $ make run +.. note:: + If email sending is disabled: ``$ make run-server`` Deployment ~~~~~~~~~~