From 1179984f6b4ee9fa97582c73eaa6d962d8588141 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Sun, 25 Apr 2021 20:51:15 +0200 Subject: docs: Actualize README This change updates several points in the README that were outdated or incorrect. --- README.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index dae5c2ff..3be20134 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ The simulator is accessible both as a ready-to-use website hosted by us at [open ## Architecture -OpenDC consists of four components: a Kotlin [simulator](/simulator), a MongoDB database, a Python Flask [API](/api), and a React.js [frontend](/frontend), each in their own subdirectories. +OpenDC consists of four components: a Kotlin simulator, a MongoDB database, a Python Flask [API](/opendc-web/opendc-web-api), and a React.js [frontend](/opendc-web/opendc-web-ui).

OpenDC Component Diagram @@ -37,7 +37,9 @@ The (Swagger/OpenAPI compliant) API spec specifies what requests the frontend ca The web server receives API requests and processes them in the database. When the frontend requests to run a new scenario, the web server adds it to the `scenarios` collection in the database and sets its `state` as `QUEUED`. -The simulator monitors the database for `QUEUED` scenarios, and simulates them as they are submitted. It writes the results to parquet files, which in turn are analysed and aggregated by a Spark pipeline. This pipeline then write the aggregated summary to the database, which the frontend can then again retrieve via the web server. +The simulator monitors the database for `QUEUED` scenarios, and simulates them as they are submitted. The results +of the simulations are processed and aggregated in memory. Afterwards, the aggregated summary is written to the database, +which the frontend can then again retrieve via the web server. ## Setup @@ -48,30 +50,26 @@ The official way to run OpenDC is using Docker. Other options include building a For all of these options, you have to create a Google API Console project and client ID, which the OpenDC frontend and web server will use to authenticate users and requests. Follow [these steps](https://developers.google.com/identity/sign-in/web/sign-in) to make such a project. In the 'Authorized JavaScript origins' and 'Authorized redirect URI' fields, be sure to add `http://localhost:8080` (frontend), `http://localhost:8081` (api) and `https://localhost:3000` (frontend dev). Download the JSON of the OAuth 2.0 client ID you created from the Credentials tab, and specifically note the `client_id`, which you'll need to build OpenDC. ### Installing Docker +OpenDC uses [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) to orchestrate the +deployment of the software stack. Please refer to [Docker Desktop](https://www.docker.com/products/docker-desktop) for +instructions on how install Docker on your machine. -GNU/Linux, Mac OS X and Windows 10 Professional users can install Docker by following the instructions [here](https://www.docker.com/products/docker). - -Users of Windows 10 Home and previous editions of Windows can use [Docker Toolbox](https://www.docker.com/products/docker-toolbox). If you're using the toolbox, don't forget to setup port forwarding (see the following subsection if you haven't done that, yet). - -#### Port Forwarding - -_Skip this if you have GNU/Linux, Mac OS X and Windows 10 Professional._ - -Open VirtualBox, navigate to the settings of your default docker VM, and go to the 'Network' tab. There, hidden in the 'Advanced' panel, is the 'Port forwarding' feature, where you can set a rule for exposing a port of the VM to the host OS. Add one from guest IP `10.0.2.15` to host IP `127.0.0.1`, both on port `8080` and `8081`. This enables you to open a browser on your host OS and navigate to `http://localhost:8080`, once the server is running. ### Running OpenDC To build and run the full OpenDC stack locally on Linux or Mac, you first need to clone the project: ```bash -# Clone the repo and its submodules git clone https://github.com/atlarge-research/opendc.git # Enter the directory cd opendc/ ``` -In the directory you just entered, you need to set up a set of environment variables. To do this, create a file called `.env` in the `opendc` folder. In this file, replace `your-google-oauth-client-id` with your `client_id` from the OAuth client ID you created and put the path of this `opendc` folder where this placeholder is currently listed: `/your/path/to/opendc`. For a standard setup, you can leave the other settings as-is. +In the directory you just entered, you need to set up a set of environment variables. +To do this, create a file called `.env` in the `opendc` folder. In this file, +replace `your-google-oauth-client-id` with your `client_id` from the OAuth client ID you created. +For a standard setup, you can leave the other settings as-is. ```.env MONGO_INITDB_ROOT_USERNAME=root @@ -87,7 +85,8 @@ OPENDC_API_BASE_URL=http://localhost:8081 We provide a list of default traces for you to experiment with. If you want to add others, place them in the `traces` directory and add entries to the database (see also [the database folder](database/mongo-init-opendc-db.sh)) -If you plan to publicly deploy, please also tweak the other settings. In that case, also check the `docker-compose.yml` for further instructions. +If you plan to publicly deploy, please also tweak the other settings. +In that case, also check the `docker-compose.yml` and `docker-compose.pod.yml` for further instructions. Now, start the server: -- cgit v1.2.3