diff --git a/README.md b/README.md index e69de29..9418cd1 100644 --- a/README.md +++ b/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 . diff --git a/docs/config/index.md b/docs/config/index.md index a025a48..2d53579 100644 --- a/docs/config/index.md +++ b/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: {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: {target="_blank"} + + + diff --git a/docs/deployment.md b/docs/deployment.md index 694f00e..28a0fe8 100644 --- a/docs/deployment.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 222b63d..75687bc 100644 --- a/docs/index.md +++ b/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}} -``` \ No newline at end of file +{% include-markdown "../README.md" %} diff --git a/docs/init.md b/docs/init.md index f4d7d91..26482b4 100644 --- a/docs/init.md +++ b/docs/init.md @@ -8,9 +8,9 @@ === "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 { @@ -18,11 +18,13 @@ } ``` - 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. + + diff --git a/mkdocs.yml b/mkdocs.yml index f113753..670d80f 100644 --- a/mkdocs.yml +++ b/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 diff --git a/projects/sbos-playground/docker-compose-dev.yml b/projects/sbos-playground/docker-compose-dev.yml index 6d060a1..c6cc5e5 100644 --- a/projects/sbos-playground/docker-compose-dev.yml +++ b/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 diff --git a/projects/sbos-playground/docker-compose.yml b/projects/sbos-playground/docker-compose.yml index 46d686d..1adbd82 100644 --- a/projects/sbos-playground/docker-compose.yml +++ b/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:-} diff --git a/projects/sbos-playground/sbos/playground/app.py b/projects/sbos-playground/sbos/playground/app.py index b2ae7cb..5f57063 100644 --- a/projects/sbos-playground/sbos/playground/app.py +++ b/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