docs: create_app docstring, multiple_apps section, and integrated.md fixes

Author: eimrek

docs/deployment/.pages

@@ -1,4 +1,5 @@
 title: "Deployment"
 nav:
     - integrated.md
+    - multiple_apps.md
     - container.md

docs/deployment/integrated.md

@@ -3,7 +3,7 @@
 The `optimade` package can be used to create a standalone web application that serves the OPTIMADE API based on a pre-configured MongoDB backend.
 In this document, we are going to use `optimade` differently and use it to add an OPTIMADE API implementation alongside an existing API that employs an Elasticsearch storage layer.
 
-Let's assume we already have a *FastAPI* application that runs an unrelated web service, and that we use an Elasticsearch backend that contains all structure data, but not necessarily in a form that OPTIMADE expects.
+Let's assume we already have a _FastAPI_ application that runs an unrelated web service, and that we use an Elasticsearch backend that contains all structure data, but not necessarily in a form that OPTIMADE expects.
 
 ## Providing the `optimade` configuration
 
@@ -13,7 +13,7 @@ If you run `optimade` code inside another application, you might want to provide
 Let's say you have a file `optimade_config.json` as part of the Python module that you use to create your OPTIMADE API.
 
 !!! tip
-    You can find more detailed information about configuring the `optimade` server in the [Configuration](../configuration.md) section.
+You can find more detailed information about configuring the `optimade` server in the [Configuration](../configuration.md) section.
 
 Before importing any `optimade` modules, you can set the `OPTIMADE_CONFIG_FILE` environment variable to refer to your config file:
 
@@ -37,30 +37,21 @@ structures.structures_coll = MyElasticsearchStructureCollection()
 
 You can imagine that `MyElasticsearchStructureCollection` either sub-classes the default `optimade` Elasticsearch implementation ([`ElasticsearchCollection`][optimade.server.entry_collections.elasticsearch.ElasticCollection]) or sub-classes [`EntryCollection`][optimade.server.entry_collections.entry_collections.EntryCollection], depending on how deeply you need to customize the default `optimade` behavior.
 
-## Mounting the OPTIMADE Python tools *FastAPI* app into an existing *FastAPI* app
+## Mounting the OPTIMADE Python tools _FastAPI_ app into an existing _FastAPI_ app
 
-Let's assume you have an existing *FastAPI* app `my_app`.
+Let's assume you have an existing _FastAPI_ app `my_app`.
 It already implements a few routers under certain path prefixes, and now you want to add an OPTIMADE implementation under the path prefix `/optimade`.
 
-First, you have to set the `root_path` in the `optimade` configuration, so that the app expects all requests to be prefixed with `/optimade`.
+The primary thing to modify is the `base_url` to match the new subpath. The easiest is to just update your configuration file or env parameters.
 
-Second, you simply mount the `optimade` app into your existing app `my_app`:
+Then one can just simply do the following:
 
 ```python
-from optimade.server.config import CONFIG
+from optimade.server.main import main as optimade
 
-CONFIG.root_path = "/optimade"
-
-from optimade.server import main as optimade
-
-optimade.add_major_version_base_url(optimade.app)
 my_app.mount("/optimade", optimade.app)
 ```
 
-!!! tip
-    In the example above, we imported `CONFIG` before `main` so that our config was loaded before app creation.
-    To avoid the need for this, the `root_path` can be set in your JSON config file, passed as an environment variable, or declared in a custom Python module (see [Configuration](../configuration.md)).
-
-See also the *FastAPI* documentation on [sub-applications](https://fastapi.tiangolo.com/advanced/sub-applications/).
+See also the _FastAPI_ documentation on [sub-applications](https://fastapi.tiangolo.com/advanced/sub-applications/).
 
-Now, if you run `my_app`, it will still serve all its routers as before and in addition it will also serve all OPTIMADE routes under `/optimade/` and the versioned URLs `/optimade/v1/`.
+Now, if you run `my_app`, it will still serve all its routers as before and in addition it will also serve all OPTIMADE routes under `/optimade/`.

docs/deployment/multiple_apps.md

@@ -0,0 +1,38 @@
+# Serve multiple OPTIMADE APIs within a single python process
+
+One can start multiple OPTIMADE API apps within a single FastAPI instance and mount them at different subpaths.
+
+This is enabled by the `create_app` method that allows to override parts of the configuration for each specific app, and set up separate loggers.
+
+Here's a simple example that sets up two OPTIMADE APIs and an Index Meta-DB respectively at subpaths `/app1`, `/app2` and `/idx`.
+
+```python
+from fastapi import FastAPI
+
+from optimade.server.config import ServerConfig
+from optimade.server.create_app import create_app
+
+parent_app = FastAPI()
+
+base_url = "http://127.0.0.1:8000"
+
+conf1 = ServerConfig()
+conf1.base_url = f"{base_url}/app1"
+conf1.mongo_database = "optimade_1"
+app1 = create_app(conf1, logger_tag="app1")
+parent_app.mount("/app1", app1)
+
+conf2 = ServerConfig()
+conf2.base_url = f"{base_url}/app2"
+conf2.mongo_database = "optimade_2"
+app2 = create_app(conf2, logger_tag="app2")
+parent_app.mount("/app2", app2)
+
+conf3 = ServerConfig()
+conf3.base_url = f"{base_url}/idx"
+conf3.mongo_database = "optimade_idx"
+app3 = create_app(conf3, index=True, logger_tag="idx")
+parent_app.mount("/idx", app3)
+```
+
+Note that `ServerConfig()` returns the configuration based on the usual sources - env variables or json file (see [Configuration](../configuration.md) section).

optimade/server/create_app.py

@@ -188,6 +188,26 @@ def create_app(
     index: bool = False,
     logger_tag: str | None = None,
 ) -> FastAPI:
+    """
+    Create and configure a FastAPI app for the OPTIMADE API.
+
+    Sets up logging, middleware, exception handlers, routers, and optional
+    test/JSONL data insertion. Can be used for both a regular OPTIMADE API
+    or the index meta-database variant.
+
+    Note that the global ServerConfig instance is read from the "OPTIMADE_"
+    env variables or the config json file, but this function allows to
+    override config options for individual apps by passing a custom ServerConfig.
+
+    Args:
+        config: ServerConfig instance to override config options specific to this app.
+        index: If True, create an index meta-database instance.
+        logger_tag: Optional tag for the logger.
+
+    Returns:
+        Configured FastAPI application.
+    """
+
     # create app-specific logger
     logger = create_logger(logger_tag, config)