docs: config and README

README.md

@@ -0,0 +1,36 @@
+# Playground
+
+## What is Playground?
+
+PlayGround is a safe building operating system (SBOS), that incorporates a structured semantic representation of the building (based on [Brick](https://brickschema.org)) to inform the safe, multi-tenant execution of untrusted applications. We use the semantic representation to implement (a) a novel graph-based capability mechanism for fine-grained and expressive access control management, and (b) a resource isolation mechanism with preemptive interventions and passive telemetry-based live resource monitoring.
+
+## Why does this matter?
+
+Despite technological and standardization victories, the pace of innovation and the adoption rate of smart building applications in the real world remains low due to safety reasons. 
+
+> I bet very few have used a real building application in the wild.
+
+Building managers are naturally reluctant to deploy third party building applications which are unvetted and possibly buggy. The inability of modern buildings to properly restrict an application's permissions also makes the application's execution generally opaque to the manager, unless intensive manual effort is invested to monitor them.
+
+Playground, is designed to tackle these issues. The goal of Playground is to encourage innovation and exploration of how modern building applications can provide value to occupants, managers, and other stakeholders while avoiding the intensive manual effort required to deploy them *safely*.
+
+
+## Citation
+
+A [paper](https://ieeexplore.ieee.org/abstract/document/10571633) describing the design philosophies and technical contributions of Playground was published in 2024 ACM/IEEE 15th International Conference on Cyber-Physical Systems (ICCPS) and was awarded as one of the 🏆best paper finalists🏆. If you find Playground to be helpful, please consider cite
+```latex
+@INPROCEEDINGS{10571633,
+  author={Fu, Xiaohan and Liu, Yihao and Koh, Jason and Hong, Dezhi and Gupta, Rajesh and Fierro, Gabe},
+  booktitle={2024 ACM/IEEE 15th International Conference on Cyber-Physical Systems (ICCPS)}, 
+  title={Playground: A Safe Building Operating System}, 
+  year={2024},
+  volume={},
+  number={},
+  pages={111-122},
+  keywords={Smart buildings;Costs;Operating systems;Buildings;Semantics;Programming;Maintenance;Brick;building;isolation;capability},
+  doi={10.1109/ICCPS61052.2024.00017}}
+```
+
+## Documentation
+
+Please find the documentation on <https://brickschema.github.io/playground/>.

docs/config/index.md

@@ -1 +1,55 @@
 # Configuration
+
+Usually a `.env` file is created in the project root directory. 
+The file can be used to configure the playground server.
+
+For example, if the default server port should be changed from `9000` to `10000`, 
+the following line can be added in the `.env` file:
+
+```dotenv title=".env"
+SERVER_PORT=10000
+```
+
+Alternatively, environment variables can also be used, and its priority is higher.
+
+```bash
+export SERVER_PORT=10000
+```
+
+For detailed environment variables precedence rules, check the section [Environment Variables Precedence](#environment-variables-precedence).
+
+!!! note
+
+    If docker-compose is used to deploy the service, and the configuration entry is not listed in the compose file,
+    the entry should be added to the "environment" section manually.
+
+## Configuration List
+
+There are three types of configurations:
+
++ [Database](db.md): Database connection 
++ [Authorization](auth.md): JWT, CORS, OAuth2
++ [Backend](backend.md): Server host, port, url, and etc.
+
+## Environment Variables Precedence
+
+=== "Docker Compose (recommended)"
+
+    > The order of precedence (highest to lowest) is as follows:
+    >
+    > 1. Set using docker compose run -e in the CLI.
+    > 2. Set with either the environment or env_file attribute but with the value interpolated from your shell or an environment file. (either your default .env file, or with the --env-file argument in the CLI).
+    > 3. Set using just the environment attribute in the Compose file.
+    > 4. Use of the env_file attribute in the Compose file.
+    > 5. Set in a container image in the ENV directive. Having any ARG or ENV setting in a Dockerfile evaluates only if there is no Docker Compose entry for environment, env_file or run --env.
+    > 
+    > Source: <https://docs.docker.com/compose/environment-variables/envvars-precedence>{target="_blank"}
+
+=== "Direct"
+
+    > Even when using a dotenv file, pydantic will still read environment variables as well as the dotenv file, environment variables will always take priority over values loaded from a dotenv file.
+    >
+    > Source: <https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support>{target="_blank"}
+
+
+

docs/deployment.md

@@ -1,8 +1,8 @@
 # Deployment
 
-## Clone the repositories
+## Clone the repository
 
-First, we need to clone the repository and work in the project directory.
+SBOS is managed as a mono-repo. Clone the repository and work in the project directory.
 
 ```bash
 git clone https://github.com/BrickSchema/playground
@@ -20,7 +20,7 @@ touch .env
 
 ## Deploy the server
 
-=== "Docker (recommended)"
+=== "Docker Compose (recommended)"
 
     In the playground directory, run
 

docs/index.md

@@ -1,32 +1 @@
-# About
-
-## What is Playground?
-
-PlayGround is a safe building operating system (SBOS), that incorporates a structured semantic representation of the building (based on [Brick](brickschema.org)) to inform the safe, multi-tenant execution of untrusted applications. We use the semantic representation to implement (a) a novel graph-based capability mechanism for fine-grained and expressive access control management, and (b) a resource isolation mechanism with preemptive interventions and passive telemetry-based live resource monitoring.
-
-## Why does this matter?
-
-Despite technological and standardization victories, the pace of innovation and the adoption rate of smart building applications in the real world remains low due to safety reasons. 
-
-> I bet very few have used a real building application in the wild.
-
-Building managers are naturally reluctant to deploy third party building applications which are unvetted and possibly buggy. The inability of modern buildings to properly restrict an application's permissions also makes the application's execution generally opaque to the manager, unless intensive manual effort is invested to monitor them.
-
-Playground, is designed to tackle these issues. The goal of Playground is to encourage innovation and exploration of how modern building applications can provide value to occupants, managers, and other stakeholders while avoiding the intensive manual effort required to deploy them *safely*.
-
-
-## Citation
-
-A [paper](https://ieeexplore.ieee.org/abstract/document/10571633) describing the design philosophies and techinical contributions of Playground was published in 2024 ACM/IEEE 15th International Conference on Cyber-Physical Systems (ICCPS) and was awarded as one of the 🏆best paper finalists🏆. If you find Playground to be helpful, please consider cite
-```latex
-@INPROCEEDINGS{10571633,
-  author={Fu, Xiaohan and Liu, Yihao and Koh, Jason and Hong, Dezhi and Gupta, Rajesh and Fierro, Gabe},
-  booktitle={2024 ACM/IEEE 15th International Conference on Cyber-Physical Systems (ICCPS)}, 
-  title={Playground: A Safe Building Operating System}, 
-  year={2024},
-  volume={},
-  number={},
-  pages={111-122},
-  keywords={Smart buildings;Costs;Operating systems;Buildings;Semantics;Programming;Maintenance;Brick;building;isolation;capability},
-  doi={10.1109/ICCPS61052.2024.00017}}
-```
+{% include-markdown "../README.md" %}

docs/init.md

@@ -8,21 +8,23 @@
 
 === "Google OAuth2"
 
-    Before using this, ensure that you have setup [Google OAuth2](config/auth.md) in the configuration.
+    Before using this, ensure that [Google OAuth2](config/auth.md) has been setup in the configuration.
 
-    Use the API `/brickapi/v1/auth/cookie/google/authorize` and the API will return a json response in the format
+    Use the API `/brickapi/v1/auth/cookie/google/authorize` and it will return a json response in the format
 
     ```json
     {
       "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?foo=bar"
     }
     ```
 
-    Open `authorization_url` in the browser and continue with your google account.
-    The page will be redirected back to the `FRONTEND_URL` entry in configuration.
-    By default, it is the url of the Swagger API if you didn't set it.
+    Open `authorization_url` in the browser and authorize with Google Account.
+    The page will be redirected back to the [FRONTEND_URL](config/backend.md#frontend_url) entry in configuration.
+    By default, it is the url of the Swagger API if not set in configuration.
 
 !!! note
 
-    You can also register the admin user in the frontend.
-    We recommand to do it in the Swagger API for convenience of debugging the setup.
+    The admin user can also be registered in the frontend.
+    However, it is recommanded to use the Swagger API for convenience of debugging the setup.
+
+

mkdocs.yml

@@ -39,6 +39,10 @@ site_name: SBOS Playground
 docs_dir: docs
 markdown_extensions:
   - admonition
+  - attr_list
+  - def_list
+  - toc:
+      permalink: true
   - pymdownx.details
   - pymdownx.highlight:
       anchor_linenums: true
@@ -50,6 +54,7 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.magiclink
 plugins:
   - include-markdown
 not_in_nav: /generated/**/*.md
@@ -59,7 +64,7 @@ nav:
       - Deployment: deployment.md
       - Initialization: init.md
       - Configuration:
-          # - config/index.md
+          - config/index.md
           - Database: config/db.md
           - Authorization: config/auth.md
           - Backend: config/backend.md

projects/sbos-playground/docker-compose-dev.yml

@@ -15,7 +15,7 @@ services:
       - core-minimal
     environment:
       DEBUG: true
-      WORKERS: 1
+      SERVER_WORKERS: 1
 #      FRONTEND_URL: http://localhost:8000
     volumes:
       - ./static:/root/sbos-playground/static

projects/sbos-playground/docker-compose.yml

@@ -52,20 +52,20 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock
       - ./app_static:/root/sbos-playground/app_static
     ports:
-      - "9000:9000"
+      - "${SERVER_PORT:-9000}:${SERVER_PORT:-9000}"
     networks:
       - sbos-network
       - isolated_nw
     environment:
       - DEBUG=false
       - CACHE=${CACHE:-true}
-      - HOST=0.0.0.0
+      - SERVER_HOST=${SERVER_HOST:-0.0.0.0}
+      - SERVER_WORKERS=${SERVER_WORKERS:-4}
       - MONGO_HOST=mongo
       - TIMESCALE_HOST=postgres
       - GRAPHDB_HOST=graphdb
       - REDIS_HOST=redis
       - ISOLATED_NETWORK_NAME=sbos-playground_isolated_nw
-      - WORKERS=${WORKERS:-4}
       - INFLUXDB_TOKEN=${INFLUXDB_TOKEN:-}
       - OAUTH_GOOGLE_CLIENT_ID=${OAUTH_GOOGLE_CLIENT_ID:-}
       - OAUTH_GOOGLE_CLIENT_SECRET=${OAUTH_GOOGLE_CLIENT_SECRET:-}

projects/sbos-playground/sbos/playground/app.py

@@ -43,9 +43,10 @@ def initialize_backend_application() -> fastapi.FastAPI:
 
     register_error_handlers(app)
 
-    from sbos.playground.services import router as api_endpoint_router
+    from sbos.playground.services import router as api_endpoint_router, redirect_docs
 
     app.include_router(router=api_endpoint_router, prefix=settings.API_PREFIX)
+    app.get("/", include_in_schema=False)(redirect_docs)
 
     return app