From 5a8a234c1c38ed607e3c4f8a4ee8f71646bc6150 Mon Sep 17 00:00:00 2001 From: Sylvain Leclerc Date: Wed, 6 Sep 2023 11:49:01 +0200 Subject: [PATCH] fix(docs): update README, removing obsolete instructions (#1552) Signed-off-by: Sylvain Leclerc Co-authored-by: Laurent LAPORTE --- Dockerfile | 2 +- README.md | 76 ++++++++++++++++++--------------------- docs/install/0-INSTALL.md | 62 +++++++++++++++++++------------- docs/install/1-CONFIG.md | 13 ++++--- docs/install/2-DEPLOY.md | 3 +- 5 files changed, 82 insertions(+), 74 deletions(-) diff --git a/Dockerfile b/Dockerfile index 631ca6c336..affdc86660 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,7 @@ ENV ANTAREST_CONF /resources/application.yaml RUN mkdir -p examples/studies -COPY ./requirements.txt /conf/ +COPY ./requirements.txt ./conf/* /conf/ COPY ./antarest /antarest COPY ./resources /resources COPY ./scripts /scripts diff --git a/README.md b/README.md index 98748de7a6..bd17aeae67 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ git clone https://github.com/AntaresSimulatorTeam/AntaREST.git cd AntaREST ``` -Install back dependencies +Install back-end dependencies ```shell script python -m pip install --upgrade pip @@ -27,13 +27,24 @@ pip install pydantic --no-binary pydantic pip install -r requirements.txt # use requirements-dev.txt if building a single binary with pyinstaller ``` -Build front +Install the front-end dependencies: ```shell script cd webapp npm install cd .. +``` + +Then build the front-end application: + - for use with pyinstaller: +```shell NODE_OPTIONS="--max-old-space-size=8192" ./scripts/build-front.sh +``` + - for other uses (docker deployement, ...): +```shell +cd webapp +npm run build +cd .. ``` @@ -43,21 +54,21 @@ Linux system: ```shell script git log -1 HEAD --format=%H > ./resources/commit_id -pyinstaller -F antarest/main.py -n server --additional-hooks-dir extra-hooks --add-data resources:resources +pyinstaller AntaresWebLinux.spec ``` Windows system: ```shell script git log -1 HEAD --format=%H > .\resources\commit_id -pyinstaller -F api_iso_antares\main.py -n server --additional-hooks-dir extra-hooks --add-data ".\resources;.\resources" +pyinstaller AntaresWebWin.spec ``` You can test the build is ok using: ```shell script -dist/server -v # Linux based system -dist\server.exe -v # Windows system +dist/AntaresWeb/AntaresWebServer -v # Linux based system +dist\AntaresWeb\AntaresWebServer.exe -v # Windows system ``` ### Using docker @@ -65,69 +76,52 @@ dist\server.exe -v # Windows system To build the docker image, use the following command: ```shell script -docker build --tag antarest -f docker/Dockerfile . +docker build --tag antarest . ``` -## Start the API +## Run the API -### Using builded binary with pyinstaller +### Using binary built with pyinstaller ```shell script -dist/server -s $STUDIES_ABSOLUTE_PATH # Linux based system -dist\server.exe -s %STUDIES_ABSOLUTE_PATH% # Windows system +dist/AntaresWeb/AntaresWebServer -c # Linux based system +dist\AntaresWeb\AntaresWebServer.exe -c # Windows system ``` -* $STUDIES_ABSOLUTE_PATH is the path of the ANTARES studies folders you wish to manipulate - ### Using docker image +You may run the back-end with default configuration using the following command: ```shell script docker run \ -p 80:5000 \ - -e GUNICORN_WORKERS=4 \ - -v $STUDIES_ABSOLUTE_PATH:/studies \ + -e GUNICORN_WORKERS=1 \ antarest ``` -* Setting the environment variable GUNICORN_WORKERS to *ALL_AVAILABLE* will make GUNICORN use 2 * nb_cpu +1 workers - * https://docs.gunicorn.org/en/stable/design.html#how-many-workers - * ALL_AVAILABLE is also the default value of GUNICORN_WORKERS if you do not set it -* $STUDIES_ABSOLUTE_PATH is the path of the ANTARES studies folders you wish to manipulate - * If you do not mount */studies* to a host path, the docker image will use the current path as the studies path -* An exemple is available in this repo in the *script* folder +However, for a complete deployment including the front-end application, and the use of an external database +and an external REDIS instance, please refer to the deployement instructions on [readthedocs website](https://antares-web.readthedocs.io/en/latest) + ### Using python directly -#### Using the dev wsgi server of Flask +#### Using uvicorn ```shell script -pip install -r ./requirements.txt -export PYTHONPATH=$PYTHONPATH:. -python ./api_iso_antares/main.py -s $STUDIES_ABSOLUTE_PATH -``` +pip install -e . -* $STUDIES_ABSOLUTE_PATH is the path of the ANTARES studies folders you wish to manipulate -* An exemple is available in this repo in the *script* folder +python ./antarest/main.py -c resources/application.yaml +``` -#### Using gunicorn wsgi server +#### Using gunicorn wsgi server with uvicorn workers ```shell script -pip install -r ./requirements.txt -export PYTHONPATH=$PYTHONPATH:. +pip install -e . -export ANTAREST_CONF=$ANTAREST_CONF_YAML_PATH +export ANTAREST_CONF=resources/application.yaml export GUNICORN_WORKERS=4 - -gunicorn --config "$YOUR_GUNICORN_CONFIG" antarest.wsgi:app +gunicorn --config conf/gunicorn.py --worker-class=uvicorn.workers.UvicornWorker antarest.wsgi:app ``` -* $YOUR_GUNICORN_CONFIG is the path of a gunicorn server configuration file - * An example is available in this repo in the *conf* folder -* Setting the environment variable GUNICORN_WORKERS to *ALL_AVAILABLE* will make GUNICORN use 2 * nb_cpu +1 workers - * https://docs.gunicorn.org/en/stable/design.html#how-many-workers - * ALL_AVAILABLE is also the default value of GUNICORN_WORKERS if you do not set it -* An exemple is available in this repo in the *script* folder - ## Examples Once you started the server, you have access to the API. diff --git a/docs/install/0-INSTALL.md b/docs/install/0-INSTALL.md index 167afb39aa..ccb86e9b63 100644 --- a/docs/install/0-INSTALL.md +++ b/docs/install/0-INSTALL.md @@ -1,46 +1,58 @@ # Introduction -Antares-Web is developed mainly in **python** and uses [FastAPI](https://fastapi.tiangolo.com/) web framework. -The front end is a [React](https://reactjs.org/) web application. A local build allows using Antares-Web as a desktop application. +Antares Web is developed mainly in **Python** and uses [FastAPI](https://fastapi.tiangolo.com/) web framework. +The front end is a [React](https://reactjs.org/) web application. +A local build allows using Antares Web as a desktop application. ## Quick start -Requirements : +Requirements: + - python : 3.8.x - node : 18.16.1 +Then perform the following steps: + 1. First clone the projet: -``` -git clone https://github.com/AntaresSimulatorTeam/AntaREST.git -cd AntaREST -``` + ```shell + git clone https://github.com/AntaresSimulatorTeam/AntaREST.git + cd AntaREST + ``` + +2. Create and activate a Python virtual environment: -2. Install back dependencies + ```shell + python3 -m venv venv + source venv/bin/activate + ``` -``` -python -m pip install --upgrade pip -pip install pydantic --no-binary pydantic -pip install -r requirements.txt # use requirements-dev.txt if building a single binary with pyinstaller -``` +3. Install dependencies to build, test or develop the back end: -3. Build front (for local mode use `cd ..; ./scripts/build-front.sh` instead of `npm run build`) + ```shell + python3 -m pip install --upgrade pip + pip install -e . # to install in development mode (editable) + pip install -r requirements-dev.txt # production, unit tests and development requirements + ``` -``` -cd webapp -npm install -npm run build -``` +4. Install dependencies to build the front end: -4. Run the application + ```shell + cd webapp + npm install + npm run build + cd .. + ``` -``` -export PYTHONPATH=$(pwd) -python antarest/main.py -c resources/application.yaml --auto-upgrade-db -``` +5. Run the application + + ```shell + python3 antarest/main.py -c resources/application.yaml --auto-upgrade-db --no-front + ``` ## Deploy -There are 2 ways to use and/or deploy the application : +There are 2 ways to use and/or deploy the application: + - As [a server application](./2-DEPLOY.md#production-server-deployment) - As [a desktop systray application](./2-DEPLOY.md#local-application-build) \ No newline at end of file diff --git a/docs/install/1-CONFIG.md b/docs/install/1-CONFIG.md index d915409934..7c82b044dd 100644 --- a/docs/install/1-CONFIG.md +++ b/docs/install/1-CONFIG.md @@ -1,8 +1,11 @@ # Application Configuration -Almost all the configuration of the application can be found in the [application.yaml](https://github.com/AntaresSimulatorTeam/AntaREST/blob/master/resources/application.yaml) file.\ -If the path to this configuration file is not explicitly given (option `-c`), the application will try to look for files in the following location (in order): -- `./config.yaml` -- `../config.yaml` -- `$HOME/.antares/config.yaml` +Almost all the configuration of the application can be found in the +[application.yaml](https://github.com/AntaresSimulatorTeam/AntaREST/blob/master/resources/application.yaml) file. +If the path to this configuration file is not explicitly provided (through the `-c` option), +the application will try to look for files in the following location (in order): + + 1. `./config.yaml` + 2. `../config.yaml` + 3. `$HOME/.antares/config.yaml` diff --git a/docs/install/2-DEPLOY.md b/docs/install/2-DEPLOY.md index 8db71603c7..5946e362f9 100644 --- a/docs/install/2-DEPLOY.md +++ b/docs/install/2-DEPLOY.md @@ -55,13 +55,12 @@ These steps should work on any linux system with docker and docker-compose insta b. Create the directory `resources/deploy/db` - 5. Run the following command to spin up the application containers: ```shell docker-compose up ``` - + 6. You can then access the application at http://localhost 7. To stop the application you can juste hit "CTRL-C" to end the containers.