diff --git a/docs/install_and_deploy.md b/docs/install_and_deploy.md index af5f3d575a..9f241be693 100644 --- a/docs/install_and_deploy.md +++ b/docs/install_and_deploy.md @@ -105,6 +105,10 @@ options: --reload enable auto-reload ``` +Now the server is up, and depending on the intended use case you may have to +create/edit some users - see [the Users page](./users.md). + + Notice that you could also use more explicit startup commands, see [below](../install_and_deploy/#serving-fractal-server-via-gunicorn) for an example based on Gunicorn. diff --git a/docs/users.md b/docs/users.md new file mode 100644 index 0000000000..c794964675 --- /dev/null +++ b/docs/users.md @@ -0,0 +1,57 @@ +The Fractal Server and Client offer a set of features to manage users +(largely based on +[fastapi-users](https://fastapi-users.github.io/fastapi-users)); the typical +use cases are: + +1. The server has access to a SLURM cluster, through the + [SLURM backend](../internals/runners/slurm), and it has multiple users - who + are also associated to SLURM users. +2. The server is used by a single user on their own machine, with the + [Process backend](../internals/runners/process/). + + +In all cases, the server startup automatically creates a default user, who also +has the superuser privileges that are necessary for managing other users. +The credentials for this user are: +``` +username=admin@fractal.xy +password=1234 +``` + +Any other user-management action has to take place through the Fractal Client, +and especially via its [`fractal user` +command](https://fractal-analytics-platform.github.io/fractal/cli_files/user.html). + +## Single user + +If no one else has access to the machine where Fractal Server is running (e.g. +your own machine), you may stick with using the default `admin@fractal.xy` user. +In this case, you may proceed using the [Fractal +Client](https://fractal-analytics-platform.github.io/fractal) to define and run +workflows, using the standard credentials. + +> **_NOTE:_** Even on your own machine, it is good practice to always modify +> the credentials of the default user, through the [`fractal user edit` +> command](https://fractal-analytics-platform.github.io/fractal/cli_files/user.html#edit). + + +## Multiple users + +If Fractal Server is deployed on a SLURM cluster, then each SLURM user who +wants to use Fractal needs to have a user registered on the Fractal Server. + + +1. After server startup, the first necessary step is to modify the credentials of the default user, +through the [`fractal user edit` +command](https://fractal-analytics-platform.github.io/fractal/cli_files/user.html#edit). + + > **_NOTE:_** Skipping the password-update step leads to a severe vulnerability! + +2. After updating the `admin@fractal.xy` user, you can register other Fractal + Server users via the Fractal Client, through the + [`fractal user register` command](https://fractal-analytics-platform.github.io/fractal/cli_files/user.html#register). + +For the full descriptions of user-management commands see the [`fractal user` +docs](https://fractal-analytics-platform.github.io/fractal/cli_files/user.html). +Note that only a superuser can run these commands (apart from the `fractal +whoami` one, which is open to any registered user). diff --git a/mkdocs.yml b/mkdocs.yml index 8502678a5c..920e67c449 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,12 +45,13 @@ theme: nav: - Home page: index.md - Install and deploy: install_and_deploy.md - - Contribute: contribute.md - Configuration: configuration.md + - Users: users.md - Internals: internals/ - Code reference: reference/ - Coverage: coverage - Web API: openapi.md + - Contribute: contribute.md watch: - fractal_server