fractal-analytics-platform · ychiucco · Oct 31, 2025 · Oct 31, 2025 · Nov 4, 2025 · Nov 4, 2025
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,12 +1,38 @@
-To configure the Fractal Server one must define some environment variables.
+To configure the Fractal Server one must define some configuration variables.
+
 Some of them are required, and the server will not start unless they are set.
 Some are optional and sensible defaults are provided.
 
-> The required variables are the following
->
-> ```
-> JWT_SECRET_KEY
-> POSTGRES_DB
-> ```
+## How to set configuration
+
+There are two possibilities for setting the configuration variables:
+
+- defining them as *environment variables* in the same environment as Fractal Server
+    ```sh
+    export VAR1=value1
+    export VAR2=value2
+    fractalctl start
+    ```
+- write them inside a file called `.fractal_server.env`, located in your current working directory
+    ```sh
+    echo "VAR1=value1
+    VAR2=value2" > .fractal_server.env
+    fractalctl start
+    ```
+
+## Minimal working example
+
+This is a minimal working example of a `.fractal_server.env`, with all the required configuration variables:
+```txt
+POSTGRES_DB=fractal_test
+JWT_SECRET_KEY=jwt_secret_key
+```
+All the other configurations will assume the defaul value.
+
+---
 
-::: fractal_server.config
+::: fractal_server.config._main
+::: fractal_server.config._database
+::: fractal_server.config._data
+::: fractal_server.config._email
+::: fractal_server.config._oauth
diff --git a/docs/install_and_deploy.md b/docs/install_and_deploy.md
@@ -1,62 +1,115 @@
 Fractal Server is the core ingredient of more deployments of the [Fractal framework](https://fractal-analytics-platform.github.io/), which also includes several other Fractal components (e.g. a web client) and also relies on external resources being availble (e.g. a PostgreSQL database and a SLURM cluster).
 
-Here we do not describe the full procedure for a full-fledged Fractal deployment in detail. Some examples of typical deployment are available as container-based demos at https://github.com/fractal-analytics-platform/fractal-containers/tree/main/examples.
+Here we just describe the basic procedure for a local deployment.
+Any production deployments will require greater attention and detail.
 
+Some examples of typical deployment are available as container-based demos at https://github.com/fractal-analytics-platform/fractal-containers/tree/main/examples.
 
-## How to install
 
-> ⚠️  The minimum supported Python version for fractal-server is 3.11.
+## Prerequisites
+
+The following will assume that:
+
+- You are using a Python version greater or equal than 3.11
+- You are working within an isolated Python environment, for example with `venv`:
+  ```
+  python3 -m venv venv
+  venv/bin/activate
+  ```
+
+- You have configured the required environment variables (see [configuration page](configuration.md)).
+
+  If you choose to declare the environment variables using the `.fractal_server.env` file, that file must be placed in the current working directory;
+
+- You have access to a dedicated Postgres database (see the [database page](internals/database_interface.md)).
+
+## How to install
 
-Fractal Server is hosted on [the PyPI index](https://pypi.org/project/fractal-server), and it can be installed with `pip` via
+Fractal Server is hosted on [PyPI](https://pypi.org/project/fractal-server), and can be installed with `pip`:
 ```
 pip install fractal-server
 ```
 
-For details on how to install Fractal Server in a development environment, see the [Development](development.md) page.
+Fractal Server is also available as a [Conda package](https://anaconda.org/conda-forge/fractal-server), but the PyPI version is the recommended one.
+
+For details on how to install Fractal Server in a development environment see the [Development](development.md) page.
+
 
 ## How to deploy
 
-Here we describe the basic steps for running Fractal Server.
+Installing `fractal-server` will automatically install `fractalctl`, its companion command-line utility that provides the basic commands for deploying Fractal Server.
 
-### 1. Set up configuration variables
+### 1. Set up the database
 
-For this command to work properly, a set of variables need to be specified,
-either as enviromnent variables or in a file like `.fractal_server.env`.
-An example of such file is
+> This only requires [DatabaseSettings](http://localhost:8000/configuration/#fractal_server.config._database.DatabaseSettings).
+
+Use the command
 ```
-JWT_SECRET_KEY=XXX
-FRACTAL_RUNNER_BACKEND=local
-POSTGRES_DB=fractal-database-name
+fractalctl set-db
 ```
+to apply the schema migrations to the database.
 
 
-> ⚠️  **`JWT_SECRET_KEY=XXX` must be replaced with a more secure string, that
-> should not be disclosed.** ⚠️
+### 2. Initialize the database
 
-More details (including default values) are available in the [Configuration](configuration.md) page.
+> This only requires [DatabaseSettings](http://localhost:8000/configuration/#fractal_server.config._database.DatabaseSettings) and, possibly, [FRACTAL_DEFAULT_GROUP_NAME](http://localhost:8000/configuration/#fractal_server.config._main.Settings.FRACTAL_DEFAULT_GROUP_NAME).
+
+With the command
+```
+fractalctl init-db-data
+```
+you can do multiple things, depending on the environment variables set and on the flag provided:
 
+  - create the default user group, by settings `FRACTAL_DEFAULT_GROUP_NAME=All`;
+  - create the first admin user, by providing the `--admin-*` flags;
+  - create the first couple resource/profile and associate users to them, providing `--resource` and `--profile`.
 
-### 2. Set up the database
-After creating a PostgreSQL database for `fractal-server`, and after setting the proper `fractal-server` configuration variables (see the [database page](internals/database_interface.md)), the command
+
+**Help message**
 ```
-fractalctl set-db
+usage: fractalctl init-db-data [-h] [--resource RESOURCE] [--profile PROFILE] [--admin-email ADMIN_EMAIL] [--admin-pwd ADMIN_PWD] [--admin-project-dir ADMIN_PROJECT_DIR]
+
+Populate database with initial data.
+
+options:
+  -h, --help            show this help message and exit
+  --resource RESOURCE   Either `default` or path to the JSON file of the first resource.
+  --profile PROFILE     Either `default` or path to the JSON file of the first profile.
+  --admin-email ADMIN_EMAIL
+                        Email of the first admin user.
+  --admin-pwd ADMIN_PWD
+                        Password for the first admin user.
+  --admin-project-dir ADMIN_PROJECT_DIR
+                        Project_dir for the first admin user.
+
 ```
-applies the appropriate schema migrations.
 
 ### 3. Start the server
 
-In the environment where Fractal Server is installed, you can run it via [`gunicorn`](https://gunicorn.org) with a command like
+Finally, we use the command
+```
+fractalctl start
+```
+to start the server using [Uvicorn](https://uvicorn.dev/).
+
+**Help message**
+
 ```
-gunicorn fractal_server.main:app \
-    --workers 2 \
-    --bind "0.0.0.0:8000" \
-    --access-logfile - \
-    --error-logfile - \
-    --worker-class fractal_server.gunicorn_fractal.FractalWorker \
-    --logger-class fractal_server.gunicorn_fractal.FractalGunicornLogger
+usage: fractalctl start [-h] [--host HOST] [-p PORT] [--reload]
+
+Start the server (with uvicorn)
+
+options:
+  -h, --help            show this help message and exit
+  --host HOST           bind socket to this host (default: 127.0.0.1)
+  -p PORT, --port PORT  bind socket to this port (default: 8000)
+  --reload              enable auto-reload
 ```
+
+### 4. Test the server
+
 To verify that the server is up, you can use the `/api/alive/` endpoint - as in
-```console
-$ curl http://localhost:8000/api/alive/
-{"alive":true,"version":"2.15.6"}
+```
+curl http://localhost:8000/api/alive/
+{"alive":true,"version":"2.17.0"}
 ```
diff --git a/docs/internals/logs.md b/docs/internals/logs.md
@@ -15,7 +15,7 @@ a logger created with
 are defined as follows:
 
 * The minimum logging level for logs to appear in the console is set by
-  [`FRACTAL_LOGGING_LEVEL`](../configuration.md/#fractal_server.config.Settings.FRACTAL_LOGGING_LEVEL);
+  [`FRACTAL_LOGGING_LEVEL`](../configuration/#fractal_server.config._main.Settings.FRACTAL_LOGGING_LEVEL);
 * The `FileHandler` logger handlers are alwasy set at the `DEBUG` level, that
   is, they write all log records.
 

diff --git a/docs/internals/users.md b/docs/internals/users.md
@@ -20,10 +20,6 @@ A Fractal user corresponds to an instance of the [`UserOAuth`](../reference/frac
 Most attributes are [the default ones from `fastapi-users`](https://fastapi-users.github.io/fastapi-users/latest/configuration/schemas/).
 
 In the startup phase, `fractal-server` creates a default user, who also has the superuser privileges that are necessary for managing other users.
-The credentials for this user are defined via the environment variables
-[`FRACTAL_ADMIN_DEFAULT_EMAIL`](../configuration.md/#fractal_server.config.Settings.FRACTAL_DEFAULT_ADMIN_EMAIL) (default: `[email protected]`)
-and
-[`FRACTAL_ADMIN_DEFAULT_PASSWORD`](../configuration.md/#fractal_server.config.Settings.FRACTAL_DEFAULT_ADMIN_PASSWORD) (default: `1234`).
 
 > **⚠️ You should always modify the password of the default user after it's created;**
 > this can be done with API calls to the `PATCH /auth/users/{id}` endpoint of the [`fractal-server` API](../openapi.md), e.g. through the `curl` command or the [Fractal command-line client](https://fractal-analytics-platform.github.io/fractal-client/reference/fractal/user/#user-edit).

diff --git a/fractal_server/__main__.py b/fractal_server/__main__.py
@@ -49,9 +49,7 @@
 # fractalctl set-db
 set_db_parser = subparsers.add_parser(
     "set-db",
-    description=(
-        "Initialise/upgrade database schemas and create first group&user."
-    ),
+    description="Initialise/upgrade database schemas.",
 )
 
 # fractalctl init-db-data

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -84,6 +84,7 @@ mkdocs-literate-nav="0.6.2"
 mkdocs-section-index="0.3.10"
 mkdocs-render-swagger-plugin="0.1.2"
 pyyaml=">=6.0.0"
+click = "8.2.1"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"