fix(doc): miscellaneous fixes for deployment docs (#463)

Shillaker · web-flow · commit 998de15aed6c · 2026-01-30T11:53:01.000+01:00
diff --git a/Makefile b/Makefile
@@ -45,6 +45,9 @@ run:
 run-py:
 		python boaviztapi/main.py
 
+run-doc:
+		cd docs && poetry run mkdocs serve
+
 $(SEMVERS):
 		poetry version $@
 		$(MAKE) npm_version
@@ -72,3 +75,9 @@ docker-build-development:
 
 docker-run-development:
 		docker run -p 5000:5000 boavizta/boaviztapi:${TIMESTAMP}
+
+compose-build:
+		docker compose build
+
+compose-up:
+		docker compose up --build
diff --git a/README.md b/README.md
@@ -46,18 +46,6 @@ $ docker run -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest
 
 Access the API at http://localhost:5000.
 
-### Install using pip package
-
-```bash
-$ pip3 install boaviztapi
-```
-
-Run the server locally with:
-
-```bash
-$ uvicorn boaviztapi.main:app --host=localhost --port 5000
-```
-
 ## :computer: Development
 
 ### Prerequisite
@@ -97,34 +85,16 @@ You can run the tests with `pytest` via:
 
 ### Create your own docker image and run it
 
-Build application package:
-
-```sh
-make install
-```
-
 Build Docker image:
 
 ```sh
-# using the makefile (recommended)
-make docker-build
-
-# manual build (requires to set version)
-docker build .
-```
-
-Run Docker image:
-
-```sh
-docker run -p 5000:5000/tcp boavizta/boaviztapi:`poetry version -s`
-```
-
-#### Alternative (if you don't have Python or Poetry)
-
-```sh
+# Using the makefile (recommended)
 make docker-build-development
-
 make docker-run-development
+
+# Manual build
+docker build . -t boavizta-test
+docker run -p 5000:5000 boavizta-test
 ```
 
 ### Deploy to AWS as serverless application
diff --git a/compose-prod.yaml b/compose-prod.yaml
@@ -0,0 +1,10 @@
+services:
+  boaviztapi:
+    image: ghcr.io/boavizta/boaviztapi:latest
+    ports:
+      - "5000:5000"
+
+  boaviztapi-doc:
+    image: ghcr.io/boavizta/boaviztapi-doc:latest
+    ports:
+      - "8080:8080"
diff --git a/compose.yaml b/compose.yaml
@@ -0,0 +1,12 @@
+services:
+  api:
+    build:
+      context: .
+    ports:
+      - "5000:5000"
+
+  docs:
+    build:
+      context: docs
+    ports:
+      - "8080:8080"
diff --git a/docs/Dockerfile b/docs/Dockerfile
@@ -1,14 +1,15 @@
-FROM python:3.7-slim-buster
+ARG PY_VERSION=3.13
+FROM python:$PY_VERSION-slim
 
 WORKDIR /docs
 
-RUN pip install mkdocs
-RUN pip install mkdocs-render-swagger-plugin
-RUN pip install mkdocs-material
+RUN pip install mkdocs \
+  mkdocs-render-swagger-plugin \
+  mkdocs-macros-plugin \
+  mkdocs-material
 
 COPY . .
 
-
 EXPOSE 8080
 
 ENTRYPOINT ["mkdocs", "serve"]
diff --git a/docs/README.md b/docs/README.md
@@ -33,9 +33,7 @@ See the "getting started" docs for [mkdocs](https://www.mkdocs.org/getting-start
 
 ```bash
 # If mkdocs is installed via poetry (preferred)
-# from the root of the cloned repository
-cd docs
-poetry run mkdocs serve
+make run-doc
 ```
 
 ```bash
diff --git a/docs/docs/config.md b/docs/docs/config.md
@@ -1,34 +1,62 @@
 # Configuration
 
-The config file located at data/config.json is used to set default values for the following parameters.
+The API can be configured to use different defaults for locations and hardware specs, as well as different levels of precision.
+
+The full list of configuration parameters and their defaults can be found in [`boaviztapi/utils/config.py`](https://github.com/Boavizta/boaviztapi/blob/main/boaviztapi/utils/config.py).
+
+## Overriding default values
+
+Each variable can be overridden using an environment variable of the same name, prefixed with `BOAVIZTA_`.
+
+For example, the `default_server` parameter can be overridden with the environment variable, `BOAVIZTA_DEFAULT_SERVER`.
+
+## CORS
+
+By default, all origins are allowed, but can be changed with the `BOAVIZTA_ALLOWED_ORIGINS` environment variable with the following format:
+
+```
+BOAVIZTA_ALLOWED_ORIGINS = '["url1", "url2", ...]'
+```
+
+For example: `BOAVIZTA_ALLOWED_ORIGINS='["https://datavizta.boavizta.org","https://boavizta.org"]'`.
+
+## Special message
+
+You can customize the home page with a special message by setting the environment variable `BOAVIZTA_SPECIAL_MESSAGE` in HTML format.
+
+For example: `BOAVIZTA_SPECIAL_MESSAGE="<p>my welcome message in HTML format</p>"`
 
 ## Default location
 
-The default location will be used if the user does not specify a ```usage_location``` in the request. 
-The parameter is used to complete the impact of electricity.
+The default location will be used if the user does not specify a `usage_location` in the request. The parameter is used to complete the impact of electricity.
 
 ```
 default_location: "EEE"
 ```
 
+This can be overridden with the `BOAVIZTA_DEFAULT_LOCATION` environment variable.
+
 ## Default archetype
 
-The default archetype will be used if the user does not specify an ```archetype``` in the request.
-Note that it must match an existing archetype ID in the archetype files.
+The default archetype will be used if the user does not specify an `archetype` in the request. Note that it must match an existing archetype ID in the archetype files.
 
 ```
 default_cpu: "DEFAULT"
 default_server: "compute_medium"
 ```
 
-## Default_criteria
+These can be overridden with the `BOAVIZTA_DEFAULT_CPU` and `BOAVIZTA_DEFAULT_SERVER` environment variables.
 
-The default criteria will be used if the user does not specify the ```criteria``` in the request.
+## Default criteria
+
+The default criteria will be used if the user does not specify the `criteria` in the request.
 
 ```
 default_criteria: ["gwp", "adp", "pe"]
 ```
 
+This can be overridden with the `BOAVIZTA_DEFAULT_CRITERIA` environment variable.
+
 ## Minimal significant figures
 
 The minimal number of significant figures will be employed if classical rounding yields a result containing more significant figures than the minimal allowed.
@@ -39,16 +67,20 @@ min_sig_fig: 1
 
 *If set to 1, the results will be rounded at least to 1 significant figures.*
 
+This can be overridden with the `BOAVIZTA_MIN_SIG_FIG` environment variable.
 
 ## Maximal significant figures
 
 The maximum number of significant figures will be employed if classical rounding yields a result containing more significant figures than the maximum allowed.
+
 ```
 max_sig_fig: 5
 ```
 
 *If set to 5, the results will be rounded to a maximum of 5 significant figures.*
 
+This can be overridden with the `BOAVIZTA_MAX_SIG_FIG` environment variable.
+
 ## Uncertainty percentage
 
 Uncertainty percentage is used to adapt the intensity of the rounding. The lower the uncertainty percentage, the lower aggressive the rounding.
@@ -59,10 +91,14 @@ uncertainty: 10
 
 *If set to 10, the rounding aggressiveness will be set to 10%.*
 
+This can be overridden with the `BOAVIZTA_UNCERTAINTY` environment variable.
+
 ## CPU name fuzzymatch threshold
 
 The CPU name fuzzymatch threshold will determine the minimum similarity between the CPU name in the request and the CPU name in the database. If the similarity is lower than the threshold, the API will not use the match.
 
 ```
 cpu_name_fuzzymatch_threshold: 62
-```
+```
+
+This can be overridden with the `BOAVIZTA_CPU_NAME_FUZZYMATCH_THRESHOLD` environment variable.
diff --git a/docs/docs/deploy.md b/docs/docs/deploy.md
@@ -1,96 +1,70 @@
 # Deploy the API
 
-## Deploy
-
-### with docker
+## Docker
 
 ```bash
-$ docker run  -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest
-```
-
-Then access api at <http://localhost:5000>
-
-### with docker-compose
-
-```yaml
-version: "3.9"
-services:
-  boaviztapi:
-    image: ghcr.io/boavizta/boaviztapi:latest
-    environment:
-      - SPECIAL_MESSAGE="<p>my welcome message in HTML format</p>"
-    ports:
-      - "5000:5000"
-  boaviztapi-doc:
-    image: ghcr.io/boavizta/boaviztapi-doc:latest
-    environment:
-      - API_URL=http://boaviztapi_url.com
-    ports:
-      - "8080:8080"
+$ docker run -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest
 ```
 
-### with pip
+Exposes the API at <http://localhost:5000>.
 
-boaviztapi pip package : [https://pypi.org/project/boaviztapi/](https://pypi.org/project/boaviztapi/)
+## Docker Compose
 
 ```bash
-$ pip3 install boaviztapi
+# Using Docker images from GCR
+docker compose -f compose-prod.yaml up
+
+# Building images from source
+docker compose up
 ```
 
-### from source
+Exposes the API at <http://localhost:5000>, and the docs at <http://localhost:8080>.
 
-#### Prerequisite
+## AWS Lambda
 
-Python 3 mandatory, python >=3.9 recommended, poetry recommended
+### Prerequisites
 
-#### clone the repo
+- [AWS](https://aws.amazon.com/) and [Serverless Framework](https://www.serverless.com/) accounts
+- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
+- [Serverless Framework CLI](https://www.serverless.com/framework/docs/getting-started)
 
-```bash
-$ git clone https://github.com/Boavizta/boaviztapi.git
+### Deployment
+
+```sh
+serverless deploy
 ```
 
-#### Setup poetry
+When the deploy succeeds, it will show you the URLs for the deployed function, and you can call the API as normal. You can query these URLs at any time with `serverless info`.
+
+## From source
+
+### Prerequisites
 
-Install poetry.
+- Python >=3.12
+- [Poetry](https://python-poetry.org/)
+- `make`
+
+### Clone the repo
 
 ```bash
-$ pip3 install poetry
+$ git clone https://github.com/Boavizta/boaviztapi.git
 ```
 
-Install dependencies and create a python virtual environment.
+### Install
 
 ```bash
 $ make install
-$ poetry shell
 ```
 
-#### Launch a development server
-
-**Once in the poetry environment**
-
-Development server uses [uvicorn](https://www.uvicorn.org/) and [fastapi](https://fastapi.tiangolo.com/), you can launch development server with the `uvicorn` CLI.
+### Launch the server
 
 ```bash
-$ uvicorn boaviztapi.main:app --host=localhost --port 5000
+$ make run
 ```
 
-You can run the tests with `pytest`.
-
-### CORS
-
-By default, all origin are allowed. If you need to limit them set env value ```ALLOWED_ORIGINS``` with the following format : ```ALLOWED_ORIGINS = '["url1", "url2", ...]'```
-
-Example : ```ALLOWED_ORIGINS='["https://datavizta.boavizta.org","https://boavizta.org"]'```
-
-### Special message
-
-You can customize the home page with a special message by setting the env value ```SPECIAL_MESSAGE`` in HTML format.
-
-Example : ```SPECIAL_MESSAGE="<p>my welcome message in HTML format</p>"```
-
-
 ## SDK
 
-**python-sdk** : [https://pypi.org/project/boaviztapi-sdk/](https://pypi.org/project/boaviztapi-sdk/)
+You can also use BoaviztaAPI directly in code with the SDKs:
 
-**rust-sdk** : [https://github.com/Boavizta/boaviztapi-sdk-rust](https://github.com/Boavizta/boaviztapi-sdk-rust)
+- **python-sdk** : [https://pypi.org/project/boaviztapi-sdk/](https://pypi.org/project/boaviztapi-sdk/)
+- **rust-sdk** : [https://github.com/Boavizta/boaviztapi-sdk-rust](https://github.com/Boavizta/boaviztapi-sdk-rust)
