From 6518461906cb30326349f535ee615f88884e33e9 Mon Sep 17 00:00:00 2001 From: Matthijs Bijman Date: Tue, 24 Jan 2017 11:58:44 +0100 Subject: Initial commit --- README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..1eccbe6f --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +# OpenDC Simulator -- cgit v1.2.3 From c96e6ffafb62bde1e08987b1fdf3c0786487f6ec Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Tue, 24 Jan 2017 12:06:09 +0100 Subject: Initial commit --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..22a173ae --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +# OpenDC Front End +## Initial setup +We use the NPM package repository to manage our third-party dependencies on the frontend. To fetch and install these dependencies, you'll need to have the [Node.js](https://nodejs.org/en/) environment installed. + +For easier fetching, we recommend the [Yarn Package Manager](https://yarnpkg.com), but the standard NPM tool will suffice, too. You can get your build setup installed by executing the following two commands: + + $ npm install -g yarn + $ npm install -g gulp + +You may need to prepend these commands with `sudo`, if you are on a Debian-based Linux machine. If you're having trouble giving NPM the necessary permissions on such a machine, have a look at [this NPM documentation page](https://docs.npmjs.com/getting-started/fixing-npm-permissions). + +## Building the project +Run the following commands from this directory to fetch dependencies and compile the code of the frontend side: + +``` +$ yarn +$ gulp +``` -- cgit v1.2.3 From 537d9fa8035b81ac52bc2104cc4e80e79b72628d Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Tue, 24 Jan 2017 12:41:55 +0100 Subject: Add README.md --- README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..52bf274a --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +# OpenDC Web Server -- cgit v1.2.3 From edbef77114dfde33524dccb22d27144570299372 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 26 Jan 2017 13:41:13 +0100 Subject: Add config instructions to README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 22a173ae..84ed0e99 100644 --- a/README.md +++ b/README.md @@ -14,5 +14,7 @@ Run the following commands from this directory to fetch dependencies and compile ``` $ yarn -$ gulp +$ gulp --config=config.json ``` + +**Note:** You need to replace `config.json` with the name / path of a real config file. This config file can be created by making a copy of the `sample_config.json` template and replacing the entries with your setup data. Make sure not to check this new config file into the VCS, as it is unique to each deployment situation. -- cgit v1.2.3 From 7f577b43420a1354fbb75c6c12dca3c9f7ecac50 Mon Sep 17 00:00:00 2001 From: leonoverweel Date: Mon, 27 Feb 2017 01:14:39 +0100 Subject: Update README.md with detailed local setup guide --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 52bf274a..1397b692 100644 --- a/README.md +++ b/README.md @@ -1 +1,47 @@ # OpenDC Web Server + +## Setup + +The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10. + +Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements. + +```bash +pip install flask +pip install flask_socketio +pip install oauth2client +pip install eventlet +``` + +Clone both this repository and the main OpenDC repository, from the same base directory. + +```bash +git clone https://github.com/tudelft-atlarge/opendc-web-server.git +git clone https://github.com/tudelft-atlarge/opendc.git +``` + +Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to create the SQLite database. (This will replace any file named `opendc.db` at the location `PATH_TO_DATABASE`.) + +```bash +python opendc/database/rebuild-database.py "PATH_TO_DATABASE" +``` + +Create a file `KEYS.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/tudelft-atlarge/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. + +```json +{ + "ROOT_DIR": "BASE_DIRECTORY", + "OAUTH_CLIENT_ID": "OAUTH_CLIENT_ID", + "DATABASE_LOCATION": "PATH_TO_DATABASE\\opendc.db", + "FLASK_SECRET": "FLASK_SECRET" +} +``` + +In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `control=`. + +Run the server. + +```bash +cd ../opendc-web-server +python main.py "PATH_TO_DATABASE\\opendc.db" +``` \ No newline at end of file -- cgit v1.2.3 From cdfce7ce038826bd99be805b7e7579c9ec5d4fc2 Mon Sep 17 00:00:00 2001 From: leonoverweel Date: Mon, 27 Feb 2017 01:19:37 +0100 Subject: Fix minor mistakes in README.md --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 1397b692..13b436ac 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to creat python opendc/database/rebuild-database.py "PATH_TO_DATABASE" ``` -Create a file `KEYS.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/tudelft-atlarge/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. +Create a file `config.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/tudelft-atlarge/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. ```json { @@ -37,11 +37,10 @@ Create a file `KEYS.json` in `opendc-web-server`, containing the following. Repl } ``` -In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `control=`. +In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=""`. Run the server. ```bash -cd ../opendc-web-server -python main.py "PATH_TO_DATABASE\\opendc.db" +python opendc-web-server/main.py config.json ``` \ No newline at end of file -- cgit v1.2.3 From 9d16ac4a196d12b016bbc08483aa883af841a8ad Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Sun, 12 Mar 2017 18:27:14 +0100 Subject: Add introduction to README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 13b436ac..d8ab48d5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # OpenDC Web Server +The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/tudelft-atlarge/opendc/blob/master/opendc-api-spec.json). + ## Setup The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10. @@ -43,4 +45,4 @@ Run the server. ```bash python opendc-web-server/main.py config.json -``` \ No newline at end of file +``` -- cgit v1.2.3 From 9bebe1599fb1230a4298ea00a7d2234d1cabef04 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Tue, 14 Mar 2017 15:01:02 +0100 Subject: Update `tudelft-atlarge` to `atlarge-research` --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d8ab48d5..20e12661 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OpenDC Web Server -The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/tudelft-atlarge/opendc/blob/master/opendc-api-spec.json). +The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). ## Setup @@ -18,8 +18,8 @@ pip install eventlet Clone both this repository and the main OpenDC repository, from the same base directory. ```bash -git clone https://github.com/tudelft-atlarge/opendc-web-server.git -git clone https://github.com/tudelft-atlarge/opendc.git +git clone https://github.com/atlarge-research/opendc-web-server.git +git clone https://github.com/atlarge-research/opendc.git ``` Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to create the SQLite database. (This will replace any file named `opendc.db` at the location `PATH_TO_DATABASE`.) @@ -28,7 +28,7 @@ Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to creat python opendc/database/rebuild-database.py "PATH_TO_DATABASE" ``` -Create a file `config.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/tudelft-atlarge/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. +Create a file `config.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. ```json { -- cgit v1.2.3 From 0af8947012f378f96710f2941e319b2a9ff3506f Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 20 Mar 2017 12:57:52 +0100 Subject: Add component diagram to README --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 20e12661..09dbe1b5 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). +## Architecture + +The following diagram shows a high-level view of the architecture of the OpenDC web server. + +![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) + ## Setup The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10. -- cgit v1.2.3 From bdb4b16c91263e7a82409d082d213e3191728c72 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 20 Mar 2017 13:33:14 +0100 Subject: Move architecture below setup in README --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 09dbe1b5..41c78f6d 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,7 @@ The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). -## Architecture - -The following diagram shows a high-level view of the architecture of the OpenDC web server. - -![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) +This document describes how to set up the web server for local development, and explains a high-level view of the web server architecture. ## Setup @@ -52,3 +48,9 @@ Run the server. ```bash python opendc-web-server/main.py config.json ``` + +## Architecture + +The following diagram shows a high-level view of the architecture of the OpenDC web server. + +![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) -- cgit v1.2.3 From 07abc587fec35122e974ae874070835fc3d35222 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 20 Mar 2017 13:52:53 +0100 Subject: Add component diagram and util package to README --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 41c78f6d..f983650c 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,25 @@ python opendc-web-server/main.py config.json ## Architecture -The following diagram shows a high-level view of the architecture of the OpenDC web server. +The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow. ![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) + +The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package. + +### Util Package + +The `Util` package handles several miscellaneous tasks: + +* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`. +* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed. +* `Exceptions`: Holds definitions for exceptions used throughough the web server. +* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database. + +### API Package + +[TO DO] + +### Models Package + +[TO DO] -- cgit v1.2.3 From aa267c79fab10500f0bab8da24a3258260869127 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 20 Mar 2017 17:11:35 +0100 Subject: Add API and models to README --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f983650c..3bdce698 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,14 @@ The `Util` package handles several miscellaneous tasks: ### API Package -[TO DO] +The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`). + +An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model. + +The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it. ### Models Package -[TO DO] +The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods. + +`Endpoint`s import these `Models` and use them to execute requests. -- cgit v1.2.3 From af446cd31ab4511630afbef020b1630dcff623c3 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 27 Mar 2017 17:03:27 +0200 Subject: Fix database rebuild procedure in README setup --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3bdce698..0478a245 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ git clone https://github.com/atlarge-research/opendc.git Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to create the SQLite database. (This will replace any file named `opendc.db` at the location `PATH_TO_DATABASE`.) ```bash -python opendc/database/rebuild-database.py "PATH_TO_DATABASE" +cd opendc/database +python rebuild-database.py "PATH_TO_DATABASE" ``` Create a file `config.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. -- cgit v1.2.3 From 3764a97616f8e3a42c2bf53b7d7ec58e9c787ede Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 27 Mar 2017 17:09:21 +0200 Subject: Clarify `config.json` parameters in README setup --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0478a245..b661314b 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ cd opendc/database python rebuild-database.py "PATH_TO_DATABASE" ``` -Create a file `config.json` in `opendc-web-server`, containing the following. Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). Replace `PATH_TO_DATABASE` with where you created the database. +Create a file `config.json` in `opendc-web-server`, containing: ```json { @@ -42,6 +42,12 @@ Create a file `config.json` in `opendc-web-server`, containing the following. Re } ``` +Make the following replacements: +* Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. +* Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). +* Replace `PATH_TO_DATABASE` with where you created the database. +* Replace `FLASK_SECRET`, come up with some string. + In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=""`. Run the server. -- cgit v1.2.3 From 9d35523b9fd8e3df22558fa57eb87c5d7dbcc7fb Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 27 Mar 2017 17:23:02 +0200 Subject: Clarify local development in README --- README.md | 72 +++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 42 insertions(+), 30 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b661314b..d38f998e 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,44 @@ The OpenDC web server is the bridge between OpenDC's frontend and database. It i This document describes how to set up the web server for local development, and explains a high-level view of the web server architecture. -## Setup +## Architecture + + +The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow. + +![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) + +The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package. + +### Util Package + +The `Util` package handles several miscellaneous tasks: + +* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`. +* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed. +* `Exceptions`: Holds definitions for exceptions used throughough the web server. +* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database. + +### API Package + +The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`). + +An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model. + +The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it. + +### Models Package + +The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods. + +`Endpoint`s import these `Models` and use them to execute requests. + +## Setup for Local Development The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10. +### Local Setup + Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements. ```bash @@ -50,39 +84,17 @@ Make the following replacements: In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=""`. +### Local Development + Run the server. ```bash -python opendc-web-server/main.py config.json +cd opendc-web-server +python main.py config.json ``` -## Architecture - -The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow. - -![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) - -The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package. - -### Util Package +Navigate to `http://localhost:8081/web-server-test` in a web browser (Chrome recommended), and open the console to see the server's response to the query in `static/index.html`. -The `Util` package handles several miscellaneous tasks: +To try a different query, edit the `path`, `method`, and/or `parameters` in `static/index.html`. -* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`. -* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed. -* `Exceptions`: Holds definitions for exceptions used throughough the web server. -* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database. - -### API Package - -The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`). - -An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model. - -The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it. - -### Models Package - -The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods. - -`Endpoint`s import these `Models` and use them to execute requests. +When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. -- cgit v1.2.3 From 59b05ac8425e34cdf41179506cdda357c59b4b12 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Mon, 27 Mar 2017 17:31:31 +0200 Subject: Add section jumps to README --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d38f998e..187d4133 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,10 @@ The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). -This document describes how to set up the web server for local development, and explains a high-level view of the web server architecture. +This document explains a high-level view of the web server architecture ([jump](#architecture)), and describes how to set up the web server for local development ([jump](#setup-for-local-development)). ## Architecture - The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow. ![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) -- cgit v1.2.3 From 1526c6b7094c6208847e1ce5f0fa416929ab4139 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 31 Mar 2017 10:08:47 +0200 Subject: Expand README.md with more setup steps Among the things added is an introductory text, a server-setup guide, and 'watch'-instructions. --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 84ed0e99..66013074 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,52 @@ -# OpenDC Front End -## Initial setup +# OpenDC Frontend + +The OpenDC frontend is the user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. It is built in TypeScript, using CreateJS for canvas interactions and Gulp for build-automation. + +## Architecture +[TODO] + +## Building Locally + +### Initial setup + +#### Setting up the server +To be able to see the frontend run in your browser, first set up the web server. The steps needed for this are listed on [the `opendc-web-server` repo](https://github.com/atlarge-research/opendc-web-server). + +Once the web-server is set up, clone [this frontend-repo](https://github.com/atlarge-research/opendc-frontend.git) into the same base-directory as the repos you cloned during server setup: + +```bash +git clone https://github.com/atlarge-research/opendc-frontend.git +``` + +Change directory to that new directory, and you're ready to continue to the frontend setup steps below. + +#### Resolving dependencies We use the NPM package repository to manage our third-party dependencies on the frontend. To fetch and install these dependencies, you'll need to have the [Node.js](https://nodejs.org/en/) environment installed. For easier fetching, we recommend the [Yarn Package Manager](https://yarnpkg.com), but the standard NPM tool will suffice, too. You can get your build setup installed by executing the following two commands: - $ npm install -g yarn - $ npm install -g gulp - +```bash +npm install -g yarn +npm install -g gulp +``` + You may need to prepend these commands with `sudo`, if you are on a Debian-based Linux machine. If you're having trouble giving NPM the necessary permissions on such a machine, have a look at [this NPM documentation page](https://docs.npmjs.com/getting-started/fixing-npm-permissions). -## Building the project +### Building the project Run the following commands from this directory to fetch dependencies and compile the code of the frontend side: -``` -$ yarn -$ gulp --config=config.json +```bash +yarn +gulp --config=config.json ``` **Note:** You need to replace `config.json` with the name / path of a real config file. This config file can be created by making a copy of the `sample_config.json` template and replacing the entries with your setup data. Make sure not to check this new config file into the VCS, as it is unique to each deployment situation. + +### Developing locally +To make development easier, we've set up a `watch` task. With this task, you can quickly see what effects a certain change has on the program. It runs in the background, automatically triggering a rebuild of relevant files on file-change. + +Start it by executing: + +```bash +gulp watch --config=config.json +``` -- cgit v1.2.3 From 569b90eed2035ca354014e1e772b13d1749e1b95 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 31 Mar 2017 10:20:48 +0200 Subject: Add section jumps to README.md introduction --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 66013074..8b07953e 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ The OpenDC frontend is the user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. It is built in TypeScript, using CreateJS for canvas interactions and Gulp for build-automation. +This document gives a high-level view of the frontend architecture ([jump](#architecture)), and describes how to set it up for local development ([jump](#setup-for-local-development)). + ## Architecture [TODO] -## Building Locally +## Setup for Local Development ### Initial setup @@ -42,7 +44,7 @@ gulp --config=config.json **Note:** You need to replace `config.json` with the name / path of a real config file. This config file can be created by making a copy of the `sample_config.json` template and replacing the entries with your setup data. Make sure not to check this new config file into the VCS, as it is unique to each deployment situation. -### Developing locally +### Automatically triggered builds To make development easier, we've set up a `watch` task. With this task, you can quickly see what effects a certain change has on the program. It runs in the background, automatically triggering a rebuild of relevant files on file-change. Start it by executing: -- cgit v1.2.3 From 8856cef9ec1615b38c59391005fead6b90018985 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 31 Mar 2017 11:03:08 +0200 Subject: Add state diagram --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 8b07953e..ec4f3186 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,13 @@ The OpenDC frontend is the user-facing component of the OpenDC stack, allowing u This document gives a high-level view of the frontend architecture ([jump](#architecture)), and describes how to set it up for local development ([jump](#setup-for-local-development)). ## Architecture + +### Interaction Model +[TODO] + +![OpenDC Frontend Interaction State Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-interaction-state-diagram.png) + +### Components [TODO] ## Setup for Local Development -- cgit v1.2.3 From f7518a4d196ccf9e3ef16829d4129fbb44242726 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 31 Mar 2017 15:00:24 +0200 Subject: Add page-overview to README.md --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ec4f3186..1717fb12 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,14 @@ This document gives a high-level view of the frontend architecture ([jump](#arch ## Architecture -### Interaction Model -[TODO] +### Application Interaction Model +Let's first take a look at how the user interacts with the frontend. + +#### Pages +The user starts at the splashpage (`index.html`) where he/she gets a first impression of OpenDC, including screenshots and features. After signing in with Google Authentication, the user is redirected to the page listing all projects (`projects.html`) shared or owned by that user. Here the user also has the possibility to open a particular project, redirecting to the main application page (`app.html`). + +#### Main Application +The main application allows the user to construct and simulate a datacenter. To understand how the user can do this, have a look at the state diagram below. It visualizes the main interactions a user can make with the application, as well as under which conditions. ![OpenDC Frontend Interaction State Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-interaction-state-diagram.png) -- cgit v1.2.3 From bb53cf703f87da8145196406e3ac81b3f0a1d579 Mon Sep 17 00:00:00 2001 From: Leon Overweel Date: Sat, 1 Apr 2017 22:04:57 +0200 Subject: Add Postman setup to README --- README.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 187d4133..f852326e 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ The following steps will guide you through setting up the OpenDC web server loca ### Local Setup +#### Install requirements + Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements. ```bash @@ -50,6 +52,8 @@ pip install oauth2client pip install eventlet ``` +#### Get the code + Clone both this repository and the main OpenDC repository, from the same base directory. ```bash @@ -57,6 +61,8 @@ git clone https://github.com/atlarge-research/opendc-web-server.git git clone https://github.com/atlarge-research/opendc.git ``` +#### Set up the database + Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to create the SQLite database. (This will replace any file named `opendc.db` at the location `PATH_TO_DATABASE`.) ```bash @@ -64,6 +70,8 @@ cd opendc/database python rebuild-database.py "PATH_TO_DATABASE" ``` +#### Configure OpenDC + Create a file `config.json` in `opendc-web-server`, containing: ```json @@ -81,7 +89,15 @@ Make the following replacements: * Replace `PATH_TO_DATABASE` with where you created the database. * Replace `FLASK_SECRET`, come up with some string. -In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=""`. +In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=` on line `2`. + +#### Set up Postman + +To easily make HTTP requests to the web server, we recommend Postman (get it [here](https://www.getpostman.com/)). + +Once Postman is installed and set up, `Import` the OpenDC requests collection (`OpenDC.postman_collection.json`). In the `Collections` tab, expand `OpenDC` and click `Create New Simulation`. This should open the request in the `Builder` pane. + +Navigate to `http://localhost:8081/my-auth-token` and copy the authentication token on this page to your clipboard. In the Postman `Builder` pane, navigate to the `Headers (2)` tab, and paste the authentication token as value for the `auth-token` header. (This token expires every hour - refresh the auth token page to get a new token.) ### Local Development @@ -92,8 +108,8 @@ cd opendc-web-server python main.py config.json ``` -Navigate to `http://localhost:8081/web-server-test` in a web browser (Chrome recommended), and open the console to see the server's response to the query in `static/index.html`. +Click `Send` in Postman to send your request and see the server's response. -To try a different query, edit the `path`, `method`, and/or `parameters` in `static/index.html`. +To try a different query, use the Postman `Builder` to edit the method, path, body, query parameters, etc. When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. -- cgit v1.2.3 From 780c08ab8b8a33ec8d08821f839f0d5dc034931b Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 3 Apr 2017 10:04:21 +0200 Subject: Rename user.ts to user-authentication.ts --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 1717fb12..1531b46e 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,13 @@ Let's first take a look at how the user interacts with the frontend. The user starts at the splashpage (`index.html`) where he/she gets a first impression of OpenDC, including screenshots and features. After signing in with Google Authentication, the user is redirected to the page listing all projects (`projects.html`) shared or owned by that user. Here the user also has the possibility to open a particular project, redirecting to the main application page (`app.html`). #### Main Application -The main application allows the user to construct and simulate a datacenter. To understand how the user can do this, have a look at the state diagram below. It visualizes the main interactions a user can make with the application, as well as under which conditions. +The main application allows the user to construct and simulate a datacenter. To understand how the user can do this, have a look at the state diagram below. It visualizes the main interactions a user can make with the application, as well as under which conditions those can happen. ![OpenDC Frontend Interaction State Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-interaction-state-diagram.png) ### Components +Under the hood, this looks as follows: + [TODO] ## Setup for Local Development -- cgit v1.2.3 From 50bd690ddde6a13e596adeee831ac04edf4c8262 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Tue, 4 Apr 2017 09:54:06 +0200 Subject: Add component diagram explanation to README --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 1531b46e..417173e6 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,16 @@ The main application allows the user to construct and simulate a datacenter. To ### Components Under the hood, this looks as follows: -[TODO] +![OpenDC Frontend Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-component-diagram.png) + +#### Entry Scripts +The entry scripts are the first entities triggered on page load of the respective pages. They are responsible for instantiating the corresponding view and controller. + +#### Controllers +In the main web-application, the controllers handle user input and state. They also initiate re-renders of views when a part of their managed state changes. There are different classes of controllers; some concerning themselves with the API connection, others with the different modes of interaction, and others with simulation-specific actions. This all is orchestrated by a central class called the `MapController`. + +#### Views +The views are responsible for drawing content to the canvas. They are split up into different layers, corresponding to the way they are rendered. ## Setup for Local Development -- cgit v1.2.3 From e5d7a8d6993b1f18912d6e3050be6a91fbfa88a5 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Tue, 4 Apr 2017 10:03:34 +0200 Subject: Add component diagram legend Fixes #16 --- README.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 417173e6..6f7251b8 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ Under the hood, this looks as follows: ![OpenDC Frontend Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-component-diagram.png) +*Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow.* + #### Entry Scripts The entry scripts are the first entities triggered on page load of the respective pages. They are responsible for instantiating the corresponding view and controller. -- cgit v1.2.3 From 2a4954077362d7b81a36a59580487972453180b4 Mon Sep 17 00:00:00 2001 From: leonoverweel Date: Tue, 4 Apr 2017 15:18:06 +0200 Subject: Add account setup to local setup guide in README --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f852326e..5cd95019 100644 --- a/README.md +++ b/README.md @@ -91,13 +91,17 @@ Make the following replacements: In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=` on line `2`. -#### Set up Postman +#### Set up Postman and OpenDC account To easily make HTTP requests to the web server, we recommend Postman (get it [here](https://www.getpostman.com/)). -Once Postman is installed and set up, `Import` the OpenDC requests collection (`OpenDC.postman_collection.json`). In the `Collections` tab, expand `OpenDC` and click `Create New Simulation`. This should open the request in the `Builder` pane. +Once Postman is installed and set up, `Import` the OpenDC requests collection (`OpenDC.postman_collection.json`). In the `Collections` tab, expand `OpenDC` and click `Create New User`. This should open the request in the `Builder` pane. -Navigate to `http://localhost:8081/my-auth-token` and copy the authentication token on this page to your clipboard. In the Postman `Builder` pane, navigate to the `Headers (2)` tab, and paste the authentication token as value for the `auth-token` header. (This token expires every hour - refresh the auth token page to get a new token.) +Navigate to `http://localhost:8081/my-auth-token` and copy the authentication token on this page to your clipboard. In the Postman `Builder` pane, navigate to the `Headers (2)` tab, and paste the authentication token as value for the `auth-token` header. (This token expires every hour - refresh the auth token page to get a new token.) + +(Optional: navigate to the `Body` tab and change the email address to the gmail address you used to get an authentication token.) + +Click `Send` in Postman to send your request and see the server's response. If it's a `200`, your account is set up! ### Local Development @@ -108,8 +112,6 @@ cd opendc-web-server python main.py config.json ``` -Click `Send` in Postman to send your request and see the server's response. - -To try a different query, use the Postman `Builder` to edit the method, path, body, query parameters, etc. +To try a different query, use the Postman `Builder` to edit the method, path, body, query parameters, etc. `Create New Simulation` is provided as an additional example. When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. -- cgit v1.2.3 From 1737d4fb0017823139bb84c847af875d848b8cd2 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Tue, 4 Apr 2017 16:47:11 +0200 Subject: Move JSON config file template to README --- README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6f7251b8..70b5cfee 100644 --- a/README.md +++ b/README.md @@ -61,14 +61,25 @@ npm install -g gulp You may need to prepend these commands with `sudo`, if you are on a Debian-based Linux machine. If you're having trouble giving NPM the necessary permissions on such a machine, have a look at [this NPM documentation page](https://docs.npmjs.com/getting-started/fixing-npm-permissions). ### Building the project -Run the following commands from this directory to fetch dependencies and compile the code of the frontend side: +First, create a configuration file called `config.json` in the root of the `opendc-frontend` directory, with the following template: + +```json +{ + "OAUTH_CLIENT_ID": "the-google-oauth-client-id", + "SERVER_BASE_URL": "http://localhost:8081" +} +``` + +Be sure to replace `the-google-oauth-client-id` with your actual OAuth client ID. + +Finally, run the following commands from this directory to fetch dependencies and compile the code of the frontend side: ```bash yarn -gulp --config=config.json +gulp ``` -**Note:** You need to replace `config.json` with the name / path of a real config file. This config file can be created by making a copy of the `sample_config.json` template and replacing the entries with your setup data. Make sure not to check this new config file into the VCS, as it is unique to each deployment situation. +*Note: If you wish to use a configuration file from a different location, pass a `--config=` parameter, providing the relative path to the file to be used.* ### Automatically triggered builds To make development easier, we've set up a `watch` task. With this task, you can quickly see what effects a certain change has on the program. It runs in the background, automatically triggering a rebuild of relevant files on file-change. @@ -76,5 +87,5 @@ To make development easier, we've set up a `watch` task. With this task, you can Start it by executing: ```bash -gulp watch --config=config.json +gulp watch ``` -- cgit v1.2.3 From 71877dddcb6a826a263ee1655417669aea702b43 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Tue, 4 Apr 2017 17:40:16 +0200 Subject: Add config clarification to README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 70b5cfee..8d28e84a 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ yarn gulp ``` -*Note: If you wish to use a configuration file from a different location, pass a `--config=` parameter, providing the relative path to the file to be used.* +*Note: If you wish to use a configuration file from a different location, pass a `--config=...` parameter to the `gulp` command, providing the relative path to the file to be used.* ### Automatically triggered builds To make development easier, we've set up a `watch` task. With this task, you can quickly see what effects a certain change has on the program. It runs in the background, automatically triggering a rebuild of relevant files on file-change. -- cgit v1.2.3 From c94d0c347fdbd8acc774df4ac17617a3f63e4507 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Sun, 9 Jul 2017 23:48:06 +0200 Subject: Delete old codebase This change removes version 1 of the OpenDC simulator codebase as it will be replaced by a complete rewrite in the Kotlin language. --- README.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index 1eccbe6f..00000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -# OpenDC Simulator -- cgit v1.2.3 From a1bf0b6c4255ab60800dcef452a47d0effe94c5a Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Sat, 22 Jul 2017 16:58:59 +0200 Subject: Create basic README for the project This change adds a basic README for the project in the repository. This README should be further extended by listing the features supported by the simulator and instructions on how to run a simulation. --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..a0928d97 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +

+ OpenDC Simulator +

+

OpenDC

+

+Collaborative Datacenter Simulation and Exploration for Everybody +

+ +## Getting the source +Download the source code by running the following code in your command prompt: +```sh +$ git clone -b kotlin https://github.com/atlarge-research/opendc-simulator.git +``` +or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/kotlin.zip) a copy of the source code as a Zip file. + +## Building +For building the source code, we use Gradle. To run gradle, enter the following +in your command prompt: +```sh +$ ./gradlew build +``` +To test the source code, run the following code in your command prompt +``` +$ ./gradlew test +``` + +## License +The code is released under the MIT license. See the `LICENSE.txt` file. -- cgit v1.2.3 From adbcee2afae0febda9da7b9109554591432aabcd Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Mon, 24 Jul 2017 11:24:13 +0200 Subject: Fix logo in README --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a0928d97..d10f9a12 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ -

- OpenDC Simulator -

-

OpenDC

+

+ OpenDC Simulator +
+ OpenDC +

Collaborative Datacenter Simulation and Exploration for Everybody

-- cgit v1.2.3 From b401ade3b4519c20c9afc1f0a8f318525ee0cecb Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 31 Jul 2017 11:59:31 +0300 Subject: Add setup.py file All previously listed external requirements of the README.md file have now been moved into this setup.py script. --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 5cd95019..6485a7a9 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,7 @@ The following steps will guide you through setting up the OpenDC web server loca Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements. ```bash -pip install flask -pip install flask_socketio -pip install oauth2client -pip install eventlet +python setup.py install ``` #### Get the code -- cgit v1.2.3 From 5c24591feb5eb932ad692c54052dd298c6d8839e Mon Sep 17 00:00:00 2001 From: Sacheendra Talluri Date: Wed, 9 Aug 2017 00:30:04 +0200 Subject: Update readme to reflect migration to MariaDB --- README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6485a7a9..24641c2f 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ Make sure you have Python 2.7 installed (if not, get it [here](https://www.pytho python setup.py install ``` +The web server also requires MariaDB >= 10.1. Instructions to install MariaDB can be found [here](https://mariadb.com/kb/en/mariadb/getting-installing-and-upgrading-mariadb/). The Docker image can be found [here](https://hub.docker.com/_/mariadb/). + #### Get the code Clone both this repository and the main OpenDC repository, from the same base directory. @@ -60,12 +62,7 @@ git clone https://github.com/atlarge-research/opendc.git #### Set up the database -Set up the database, replacing `PATH_TO_DATABASE` with where you'd like to create the SQLite database. (This will replace any file named `opendc.db` at the location `PATH_TO_DATABASE`.) - -```bash -cd opendc/database -python rebuild-database.py "PATH_TO_DATABASE" -``` +The database can be rebuilt by using the `schema.sql` file from main opendc repository. #### Configure OpenDC @@ -73,18 +70,22 @@ Create a file `config.json` in `opendc-web-server`, containing: ```json { - "ROOT_DIR": "BASE_DIRECTORY", - "OAUTH_CLIENT_ID": "OAUTH_CLIENT_ID", - "DATABASE_LOCATION": "PATH_TO_DATABASE\\opendc.db", - "FLASK_SECRET": "FLASK_SECRET" + "ROOT_DIR": "BASE_DIRECTORY", + "OAUTH_CLIENT_ID": "OAUTH_CLIENT_ID", + "FLASK_SECRET": "FLASK_SECRET", + "MYSQL_DATABASE": "opendc", + "MYSQL_USER": "opendc", + "MYSQL_PASSWORD": "opendcpassword", + "MYSQL_HOST": "127.0.0.1", + "MYSQL_PORT": 3306 } ``` Make the following replacements: * Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. * Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). -* Replace `PATH_TO_DATABASE` with where you created the database. * Replace `FLASK_SECRET`, come up with some string. +* Replace the `MYSQL_*` variables with the correct settings for accessing the MariaDB database that was just created. In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=` on line `2`. -- cgit v1.2.3 From 09596c3c5a6a2a44675f170106bb38746229e02a Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Sat, 23 Sep 2017 09:48:38 +0200 Subject: Remove old frontend --- README.md | 91 --------------------------------------------------------------- 1 file changed, 91 deletions(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index 8d28e84a..00000000 --- a/README.md +++ /dev/null @@ -1,91 +0,0 @@ -# OpenDC Frontend - -The OpenDC frontend is the user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. It is built in TypeScript, using CreateJS for canvas interactions and Gulp for build-automation. - -This document gives a high-level view of the frontend architecture ([jump](#architecture)), and describes how to set it up for local development ([jump](#setup-for-local-development)). - -## Architecture - -### Application Interaction Model -Let's first take a look at how the user interacts with the frontend. - -#### Pages -The user starts at the splashpage (`index.html`) where he/she gets a first impression of OpenDC, including screenshots and features. After signing in with Google Authentication, the user is redirected to the page listing all projects (`projects.html`) shared or owned by that user. Here the user also has the possibility to open a particular project, redirecting to the main application page (`app.html`). - -#### Main Application -The main application allows the user to construct and simulate a datacenter. To understand how the user can do this, have a look at the state diagram below. It visualizes the main interactions a user can make with the application, as well as under which conditions those can happen. - -![OpenDC Frontend Interaction State Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-interaction-state-diagram.png) - -### Components -Under the hood, this looks as follows: - -![OpenDC Frontend Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-frontend/master/images/opendc-frontend-component-diagram.png) - -*Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow.* - -#### Entry Scripts -The entry scripts are the first entities triggered on page load of the respective pages. They are responsible for instantiating the corresponding view and controller. - -#### Controllers -In the main web-application, the controllers handle user input and state. They also initiate re-renders of views when a part of their managed state changes. There are different classes of controllers; some concerning themselves with the API connection, others with the different modes of interaction, and others with simulation-specific actions. This all is orchestrated by a central class called the `MapController`. - -#### Views -The views are responsible for drawing content to the canvas. They are split up into different layers, corresponding to the way they are rendered. - -## Setup for Local Development - -### Initial setup - -#### Setting up the server -To be able to see the frontend run in your browser, first set up the web server. The steps needed for this are listed on [the `opendc-web-server` repo](https://github.com/atlarge-research/opendc-web-server). - -Once the web-server is set up, clone [this frontend-repo](https://github.com/atlarge-research/opendc-frontend.git) into the same base-directory as the repos you cloned during server setup: - -```bash -git clone https://github.com/atlarge-research/opendc-frontend.git -``` - -Change directory to that new directory, and you're ready to continue to the frontend setup steps below. - -#### Resolving dependencies -We use the NPM package repository to manage our third-party dependencies on the frontend. To fetch and install these dependencies, you'll need to have the [Node.js](https://nodejs.org/en/) environment installed. - -For easier fetching, we recommend the [Yarn Package Manager](https://yarnpkg.com), but the standard NPM tool will suffice, too. You can get your build setup installed by executing the following two commands: - -```bash -npm install -g yarn -npm install -g gulp -``` - -You may need to prepend these commands with `sudo`, if you are on a Debian-based Linux machine. If you're having trouble giving NPM the necessary permissions on such a machine, have a look at [this NPM documentation page](https://docs.npmjs.com/getting-started/fixing-npm-permissions). - -### Building the project -First, create a configuration file called `config.json` in the root of the `opendc-frontend` directory, with the following template: - -```json -{ - "OAUTH_CLIENT_ID": "the-google-oauth-client-id", - "SERVER_BASE_URL": "http://localhost:8081" -} -``` - -Be sure to replace `the-google-oauth-client-id` with your actual OAuth client ID. - -Finally, run the following commands from this directory to fetch dependencies and compile the code of the frontend side: - -```bash -yarn -gulp -``` - -*Note: If you wish to use a configuration file from a different location, pass a `--config=...` parameter to the `gulp` command, providing the relative path to the file to be used.* - -### Automatically triggered builds -To make development easier, we've set up a `watch` task. With this task, you can quickly see what effects a certain change has on the program. It runs in the background, automatically triggering a rebuild of relevant files on file-change. - -Start it by executing: - -```bash -gulp watch -``` -- cgit v1.2.3 From b32c5c06ee844072a760f776e5f37f7c32c97c8f Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 15:05:50 +0200 Subject: Update metadata and docs --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..36ba218f --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# OpenDC Frontend + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. + + +## Architecture + +The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. + +### Pages + +// + +### Components & Containers + +// + +### State Management + +// + +### API Interaction + +// -- cgit v1.2.3 From 906845d8c379701b948d4f2dcf954cbb01177412 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 15:17:42 +0200 Subject: Add info on pages to README.md --- README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 36ba218f..2805bf16 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,23 @@ The user-facing component of the OpenDC stack, allowing users to build and inter ## Architecture -The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. +The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. The app uses client-side routing (with `react-router`), meaning that the only HTML file needed to be served is a `index.html` file. ### Pages -// +All pages are represented by a component in the `src/pages` directory. There are components for the following pages: + +**Home.js** - Entry page (`/`) + +**Simulations.js** - Overview of simulations the user (`/simulations`) + +**App.js** - Main application, with datacenter construction and simulation UI (`/simulations/:simulationId` and `/simulations/:simulationId/experiments/:experimentId`) + +**Experiments.js** - Overview of experiments of the current simulation (`/simulations/:simulationId/experiments`) + +**Profile.js** - Profile of the current user (`/profile`) + +**NotFound.js** - 404 page to appear when route is invalid (`/*`) ### Components & Containers -- cgit v1.2.3 From f3bddcbc8273695ab6247b3f0f54f9c930757f2b Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 17:30:21 +0200 Subject: Continue README.md documentation --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2805bf16..396c87d6 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ All pages are represented by a component in the `src/pages` directory. There are **Home.js** - Entry page (`/`) -**Simulations.js** - Overview of simulations the user (`/simulations`) +**Simulations.js** - Overview of simulations of the user (`/simulations`) **App.js** - Main application, with datacenter construction and simulation UI (`/simulations/:simulationId` and `/simulations/:simulationId/experiments/:experimentId`) @@ -23,16 +23,16 @@ All pages are represented by a component in the `src/pages` directory. There are **Profile.js** - Profile of the current user (`/profile`) -**NotFound.js** - 404 page to appear when route is invalid (`/*`) +**NotFound.js** - 404 page to appear when the route is invalid (`/*`) ### Components & Containers -// +The building blocks of the UI are divided into so-called *components* and *containers* (as [encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of Redux). *Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, are wrappers around *components*, injecting state through the properties of the components they wrap. ### State Management -// +Almost all state is kept in a central Redux store. State is kept there in an immutable form, only to be modified through actions being dispatched. These actions are contained in the `src/actions` folder, and the reducers (managing how state is updated according to dispatched actions) are located in `src/reducers`. If you're not familiar with the Redux approach to state management, have a look at [their official documentation](http://redux.js.org/). ### API Interaction -// +The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API fetch procedures are written with the help of `redux-saga`. Learn more about this way of getting API data in Redux on [their official documentation](https://redux-saga.js.org/). -- cgit v1.2.3 From faa60f80e9f5ec22a2576e477714e2c2cd56054f Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 19:58:37 +0200 Subject: Dynamically choose socket.io URL to connect to --- README.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 396c87d6..ae90ee5a 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,22 @@ The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. +## Get Up and Running +To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). + +```bash +yarn +yarn start +``` + +This will start a development server running on [`localhost:3000`](http://localhost:3000), watching for changes you make to the code and rebuilding automatically when you save changes. + +To compile everything for camera-ready deployment, use the following command: + +```bash +yarn build +``` + ## Architecture The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. The app uses client-side routing (with `react-router`), meaning that the only HTML file needed to be served is a `index.html` file. @@ -35,4 +51,4 @@ Almost all state is kept in a central Redux store. State is kept there in an imm ### API Interaction -The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API fetch procedures are written with the help of `redux-saga`. Learn more about this way of getting API data in Redux on [their official documentation](https://redux-saga.js.org/). +The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API fetch procedures are written with the help of `redux-saga`. The [official documentation](https://redux-saga.js.org/) of `redux-saga` can be a helpful aid in understanding that part of the codebase. -- cgit v1.2.3 From 320ca19c49c4ddbedbd95ffdd481994892f263ff Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 20:31:26 +0200 Subject: Use env variables for logging and oauth control --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index ae90ee5a..8f2cdceb 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,24 @@ The user-facing component of the OpenDC stack, allowing users to build and inter ## Get Up and Running -To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). + +Looking for the entire stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually. + +### Installation + +To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). ```bash yarn +``` + +### Running the development server + +First, you need to have a Google OAuth client ID set up. Check the [documentation of the main OpenDC repo](https://github.com/atlarge-research/opendc) if you're not sure how to do this. Once you have such an ID, you need to set it as environment variable `REACT_APP_OAUTH_CLIENT_ID`. One way of doing this is to create an `.env` file with content `REACT_APP_OAUTH_CLIENT_ID=YOUR_ID` (`YOUR_ID` without quotes), in the root directory of this repo. + +Once you've set this variable, you're ready to start the development server: + +```bash yarn start ``` -- cgit v1.2.3 From e722cf117d0e3ebac20237f96764fb08cab49a62 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 22 Sep 2017 20:33:36 +0200 Subject: Improve OpenDC full stack reminder --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8f2cdceb..fe3b3e14 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The user-facing component of the OpenDC stack, allowing users to build and inter ## Get Up and Running -Looking for the entire stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually. +*Looking for the full OpenDC stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually.* ### Installation -- cgit v1.2.3 From 84f817d8bd8b0f1e1e75a84e73cadea0b5d5f966 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 25 Sep 2017 12:29:48 +0200 Subject: Add experimental tool disclaimer to entry page --- README.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index fe3b3e14..a4ca63a0 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,8 @@ To compile everything for camera-ready deployment, use the following command: yarn build ``` +**Note:** Perhaps this goes without saying, but for any functionality beyond visiting the entry page, a server backend running in the background is necessary. The easiest way to do this is to have an OpenDC docker container running, see [the main repo](https://github.com/atlarge-research/opendc) for more information on how to do this. + ## Architecture The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. The app uses client-side routing (with `react-router`), meaning that the only HTML file needed to be served is a `index.html` file. -- cgit v1.2.3 From a1589e75358558eada7ffc2efc7e3fa7160d233e Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 25 Sep 2017 13:50:49 +0200 Subject: Reformat codebase and fix spelling errors --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 24641c2f..8ba5e72c 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ The `Util` package handles several miscellaneous tasks: * `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`. * `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed. -* `Exceptions`: Holds definitions for exceptions used throughough the web server. +* `Exceptions`: Holds definitions for exceptions used throughout the web server. * `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database. ### API Package -- cgit v1.2.3 From d3627833f2fc09b5388999265a3ab203f54fc750 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 28 Sep 2017 09:28:22 +0200 Subject: Add testing documentation to README.md --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index a4ca63a0..f163e114 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The user-facing component of the OpenDC stack, allowing users to build and inter ## Get Up and Running -*Looking for the full OpenDC stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually.* +Looking for the full OpenDC stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually. ### Installation @@ -37,6 +37,7 @@ yarn build **Note:** Perhaps this goes without saying, but for any functionality beyond visiting the entry page, a server backend running in the background is necessary. The easiest way to do this is to have an OpenDC docker container running, see [the main repo](https://github.com/atlarge-research/opendc) for more information on how to do this. + ## Architecture The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. The app uses client-side routing (with `react-router`), meaning that the only HTML file needed to be served is a `index.html` file. @@ -68,3 +69,21 @@ Almost all state is kept in a central Redux store. State is kept there in an imm ### API Interaction The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API fetch procedures are written with the help of `redux-saga`. The [official documentation](https://redux-saga.js.org/) of `redux-saga` can be a helpful aid in understanding that part of the codebase. + + +## Tests + +Files containing tests can be recognized by the `.test.js` suffix. They are usually located right next to the source code they are testing, to make discovery easier. + +### Running all tests + +The following command runs all tests in the codebase. On top of this, it also watches the code for changes and reruns the tests when files are changed, automatically. + +```bash +yarn test +``` + + +## License + +The code is released under the MIT license. See `LICENSE.md`. -- cgit v1.2.3 From 532aa9c9241de0b658499ea4bb04e1b3b7035082 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 28 Sep 2017 14:14:13 +0200 Subject: Add notice about react-konva --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f163e114..0b35877e 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,9 @@ All pages are represented by a component in the `src/pages` directory. There are ### Components & Containers -The building blocks of the UI are divided into so-called *components* and *containers* (as [encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of Redux). *Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, are wrappers around *components*, injecting state through the properties of the components they wrap. +The building blocks of the UI are divided into so-called *components* and *containers* ([as encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of Redux). *Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, are wrappers around *components*, injecting state through the properties of the components they wrap. + +Even the canvas (the main component of the app) is built using React components, with the help of the `react-konva` module. To illustrate: A rectangular object on the canvas is defined in a way that is not very different from how we define a standard `div` element on the splashpage. ### State Management @@ -77,7 +79,7 @@ Files containing tests can be recognized by the `.test.js` suffix. They are usua ### Running all tests -The following command runs all tests in the codebase. On top of this, it also watches the code for changes and reruns the tests when files are changed, automatically. +The following command runs all tests in the codebase. On top of this, it also watches the code for changes and reruns the tests whenever any file is saved. ```bash yarn test -- cgit v1.2.3 From f29305d4c966af83a0a842f78dcb7adb7128b37c Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 28 Sep 2017 21:41:21 +0200 Subject: Improve README header --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0b35877e..ce4cb06d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,11 @@ -# OpenDC Frontend +

+ OpenDC +
+ OpenDC Frontend +

+

+Collaborative Datacenter Simulation and Exploration for Everybody +

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -- cgit v1.2.3 From b87faa0bccf661a2b6a948d9420d52a19a63d9a2 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 28 Sep 2017 21:41:48 +0200 Subject: Improve README header --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8ba5e72c..6f66b6af 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,11 @@ -# OpenDC Web Server +

+ OpenDC +
+ OpenDC Web Server +

+

+Collaborative Datacenter Simulation and Exploration for Everybody +

The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). -- cgit v1.2.3 From f78c27450a5a2f76a8f78070cc08d2cbfa488ed0 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 29 Sep 2017 09:55:14 +0200 Subject: Update README --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d10f9a12..db249c1d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- OpenDC Simulator + OpenDC
- OpenDC + OpenDC Simulator

Collaborative Datacenter Simulation and Exploration for Everybody @@ -15,12 +15,11 @@ $ git clone -b kotlin https://github.com/atlarge-research/opendc-simulator.git or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/kotlin.zip) a copy of the source code as a Zip file. ## Building -For building the source code, we use Gradle. To run gradle, enter the following -in your command prompt: +For building the source code, we use Gradle. To run gradle, enter the following in your command prompt: ```sh $ ./gradlew build ``` -To test the source code, run the following code in your command prompt +To test the source code, run the following code in your command prompt: ``` $ ./gradlew test ``` -- cgit v1.2.3 From b2e947f874363aa78c0b79fa10c519889fca832d Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 29 Sep 2017 10:40:11 +0200 Subject: Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index ce4cb06d..7c3832df 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Even the canvas (the main component of the app) is built using React components, ### State Management -Almost all state is kept in a central Redux store. State is kept there in an immutable form, only to be modified through actions being dispatched. These actions are contained in the `src/actions` folder, and the reducers (managing how state is updated according to dispatched actions) are located in `src/reducers`. If you're not familiar with the Redux approach to state management, have a look at [their official documentation](http://redux.js.org/). +Almost all state is kept in a central Redux store. State is kept there in an immutable form, only to be modified through actions being dispatched. These actions are contained in the `src/actions` folder, and the reducers (managing how state is updated according to dispatched actions) are located in `src/reducers`. If you're not familiar with the Redux approach to state management, have a look at their [official documentation](http://redux.js.org/). ### API Interaction -- cgit v1.2.3 From 2bd387bfde51a0193721e7755a273f5b8067782d Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 29 Sep 2017 10:44:40 +0200 Subject: Add travis badge to README --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 7c3832df..41ca9451 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Collaborative Datacenter Simulation and Exploration for Everybody

+[![Build Status](https://travis-ci.org/atlarge-research/opendc-frontend.svg?branch=master)](https://travis-ci.org/atlarge-research/opendc-frontend) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From 562b2eb438cb09ae617fcc481d0e2a3950a71565 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Sat, 30 Sep 2017 15:46:34 +0200 Subject: Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 41ca9451..43b7ba9a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Looking for the full OpenDC stack? Check out [the main OpenDC repo](https://gith ### Installation -To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). +To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). Once you have those installed, run the following command from the root directory of this repo: ```bash yarn -- cgit v1.2.3 From 2c26e9c91c945af065770c323e8b80a9f5104379 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Sun, 1 Oct 2017 12:01:42 +0200 Subject: chore: Add Travis shield to README --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index db249c1d..ef59c74a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,21 @@

- OpenDC + + OpenDC +
OpenDC Simulator

Collaborative Datacenter Simulation and Exploration for Everybody

+

+ + Build Status + + + MIT License + +

## Getting the source Download the source code by running the following code in your command prompt: -- cgit v1.2.3 From 606d1de0be09f3597165248f65d54e158a13860c Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Wed, 4 Oct 2017 23:17:57 +0200 Subject: Add prettier badge to README --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 43b7ba9a..55d3db00 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Collaborative Datacenter Simulation and Exploration for Everybody [![Build Status](https://travis-ci.org/atlarge-research/opendc-frontend.svg?branch=master)](https://travis-ci.org/atlarge-research/opendc-frontend) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From 886877950b1a2b4006d1f5dbe93367c086e213a0 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Sat, 28 Oct 2017 12:15:25 +0200 Subject: Upgrade dependencies --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 55d3db00..60094fe8 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Collaborative Datacenter Simulation and Exploration for Everybody [![Build Status](https://travis-ci.org/atlarge-research/opendc-frontend.svg?branch=master)](https://travis-ci.org/atlarge-research/opendc-frontend) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) +[![bitHound Overall Score](https://www.bithound.io/github/atlarge-research/opendc-frontend/badges/score.svg)](https://www.bithound.io/github/atlarge-research/opendc-frontend) The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From 0ccd0fc94b61ffc1c82b75d72f95e85bf07c193c Mon Sep 17 00:00:00 2001 From: Making GitHub Delicious Date: Thu, 2 Nov 2017 04:13:14 -0400 Subject: add waffle.io badge --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 55d3db00..af1df759 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +[![Waffle.io - Columns and their card count](https://badge.waffle.io/atlarge-research/opendc-frontend.png?columns=all)](https://waffle.io/atlarge-research/opendc-frontend?utm_source=badge)

OpenDC
-- cgit v1.2.3 From 09aa9c967d0b1a775487754d30f4f3124bcf5f87 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 2 Nov 2017 09:14:27 +0100 Subject: Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index af1df759..9a57534d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ -[![Waffle.io - Columns and their card count](https://badge.waffle.io/atlarge-research/opendc-frontend.png?columns=all)](https://waffle.io/atlarge-research/opendc-frontend?utm_source=badge)

OpenDC
@@ -10,7 +9,8 @@ Collaborative Datacenter Simulation and Exploration for Everybody [![Build Status](https://travis-ci.org/atlarge-research/opendc-frontend.svg?branch=master)](https://travis-ci.org/atlarge-research/opendc-frontend) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) +[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![Waffle.io - Columns and their card count](https://badge.waffle.io/atlarge-research/opendc-frontend.png?columns=all)](https://waffle.io/atlarge-research/opendc-frontend?utm_source=badge) The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From b23b0bf21e9b56a5af18a41940dc94589f26e68c Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 1 Dec 2017 14:29:37 +0100 Subject: Center badgess on README.md --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b1e15aad..0d93156b 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,16 @@ OpenDC Frontend

-Collaborative Datacenter Simulation and Exploration for Everybody + Collaborative Datacenter Simulation and Exploration for Everybody

-[![Build Status](https://travis-ci.org/atlarge-research/opendc-frontend.svg?branch=master)](https://travis-ci.org/atlarge-research/opendc-frontend) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) -[![bitHound Overall Score](https://www.bithound.io/github/atlarge-research/opendc-frontend/badges/score.svg)](https://www.bithound.io/github/atlarge-research/opendc-frontend)
-[![Waffle.io - Columns and their card count](https://badge.waffle.io/atlarge-research/opendc-frontend.png?columns=all)](https://waffle.io/atlarge-research/opendc-frontend?utm_source=badge) +

+ Build Status + License: MIT + styled with prettier + bitHound Overall Score
+ Waffle.io - Columns and their card count +

The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From 5ce639ef8c86ebc296b7bce30984a84f9a1eb7b0 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Thu, 17 May 2018 22:06:16 +0200 Subject: Update README.md --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0d93156b..5850cc27 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,7 @@

Build Status License: MIT - styled with prettier - bitHound Overall Score
+ styled with prettier
Waffle.io - Columns and their card count

-- cgit v1.2.3 From 91613530ca6876f0376b2878e98538c3879a29a1 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Thu, 12 Jul 2018 17:38:18 +0200 Subject: docs: Update download instructions in README (#25) This change updates download instructions for the source code in the README. The instructions reference an old branch that does not exist anymore since the transition to the Kotlin codebase. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ef59c74a..fa8a0ba9 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ Collaborative Datacenter Simulation and Exploration for Everybody ## Getting the source Download the source code by running the following code in your command prompt: ```sh -$ git clone -b kotlin https://github.com/atlarge-research/opendc-simulator.git +$ git clone https://github.com/atlarge-research/opendc-simulator.git ``` -or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/kotlin.zip) a copy of the source code as a Zip file. +or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/master.zip) a copy of the source code as a Zip file. ## Building For building the source code, we use Gradle. To run gradle, enter the following in your command prompt: -- cgit v1.2.3 From d8e7931e87990ee7fab41879b7d35a5fc3c72647 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 15 Mar 2019 17:16:52 +0100 Subject: Remove Waffle.io badge Unfortunately, the Waffle service is shutting down. For now, we'll stick to GH issues then! --- README.md | 1 - 1 file changed, 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 5850cc27..44858b69 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ Build Status License: MIT styled with prettier
- Waffle.io - Columns and their card count

The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. -- cgit v1.2.3 From 4cc3c6dea5c5536d47fcbaf8414d74de7b6fdc4b Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Fri, 9 Nov 2018 14:30:28 +0100 Subject: docs: Rewrite README for 2.x release This change gives an overhaul to the README for the release of version 2.x of the simulator. --- README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 95 insertions(+), 17 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index fa8a0ba9..54fa77cb 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,8 @@ OpenDC
- OpenDC Simulator + odcsim

-

-Collaborative Datacenter Simulation and Exploration for Everybody -

Build Status @@ -17,22 +14,103 @@ Collaborative Datacenter Simulation and Exploration for Everybody

-## Getting the source -Download the source code by running the following code in your command prompt: -```sh -$ git clone https://github.com/atlarge-research/opendc-simulator.git +## Introduction +**odcsim** is a framework for discrete event simulation in Kotlin and Java, used +by the [OpenDC](https://opendc.org) project. +Simulations are defined in terms of a hierarchical grouping of actors +and the interactions between these actors +([Actor model](https://en.wikipedia.org/wiki/Actor_model)), using +an API very similar to [Akka Typed](https://doc.akka.io/docs/akka/current/typed/index.html). + +## Documentation +Check out the [Getting Started](#getting-started) section for a quick +overview. +The documentation is located in the [docs/](docs/) directory and is divided as follows: +* [Main Concepts](docs/concepts.md) +* [Building a Model](docs/build.md) +* [Running a Model](docs/run.md) +* [Pre-built Models](docs/models.md) +* [API Reference](https://atlarge-research.github.io/opendc-simulator) +* [Contributing Guide](CONTRIBUTING.md) + +## Getting Started + +### Installation +Please add the required packages as dependency in your project. +Releases are available in the [Maven Central Repository](https://search.maven.org/). + +The package `odcsim-core` is required to construct a simulation model. +A `odcsim-engine-*` package is needed for running the simulation +model. + +**Gradle** +```groovy +compile 'com.atlarge.odcsim:odcsim-core:2.0.0' +compile 'com.atlarge.odcsim:odcsim-engine-omega:2.0.0' ``` -or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/master.zip) a copy of the source code as a Zip file. -## Building -For building the source code, we use Gradle. To run gradle, enter the following in your command prompt: -```sh -$ ./gradlew build +**Maven** +```xml + + com.atlarge.odcsim + odcsim-core + 2.0.0 + + + + com.atlarge.odcsim + odcsim-engine-omega + 2.0.0 + ``` -To test the source code, run the following code in your command prompt: + +### Construction of Simulation Model +Let's construct a simple simulation model of a single car actor. +The car will alternately drive and park for a while. When it starts +driving (or parking), it will print the current simulation time. + + +```kotlin +import com.atlarge.odcsim.Behavior +import com.atlarge.odcsim.coroutines.suspending +import com.atlarge.odcsim.coroutines.dsl.timeout + +fun car(): Behavior = + suspending { ctx -> + while (true) { + println("Start parking at ${ctx.time}") + val parkingDuration = 5.0 + timeout(parkingDuration) + + println("Start driving at ${ctx.time}") + val tripDuration = 2.0 + timeout(tripDuration) + } + + stopped() + } ``` -$ ./gradlew test + +### Running Simulation +Running the constructed simulation model requires an implementation +of the `ActorSystem` interface provided by one of the `odcsim-engine-*` +packages. The [ServiceLoader](https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html) +class found in the JDK can be used to locate the `ActorSystem` implementation on the classpath. +```kotlin +import com.atlarge.odcsim.ActorSystemFactory +import java.util.ServiceLoader + +val factory = ServiceLoader.load(ActorSystemFactory::class.java).first() +val system = factory(car(), name = "car") +system.run(until = 10.0) +system.terminate() ``` -## License -The code is released under the MIT license. See the `LICENSE.txt` file. +## Contributing +### Contributing Guide +Read our [contributing guide](CONTRIBUTING.md) to learn about our +development process, how to propose bug fixes and improvements, and how +to build and test your changes to the project. + +### License +**odcsim** is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). -- cgit v1.2.3 From 6ca0ae07669d20a5a34ef697610df90754024035 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Wed, 20 Nov 2019 17:51:58 +0100 Subject: refactor: Move build logic to buildSrc --- README.md | 81 +++++---------------------------------------------------------- 1 file changed, 6 insertions(+), 75 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 54fa77cb..b4da4287 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ OpenDC
- odcsim + OpenDC

@@ -13,6 +13,10 @@ MIT License

+

+ Collaborative Datacenter Simulation and Exploration for Everybody +

+ ## Introduction **odcsim** is a framework for discrete event simulation in Kotlin and Java, used @@ -33,79 +37,6 @@ The documentation is located in the [docs/](docs/) directory and is divided as f * [API Reference](https://atlarge-research.github.io/opendc-simulator) * [Contributing Guide](CONTRIBUTING.md) -## Getting Started - -### Installation -Please add the required packages as dependency in your project. -Releases are available in the [Maven Central Repository](https://search.maven.org/). - -The package `odcsim-core` is required to construct a simulation model. -A `odcsim-engine-*` package is needed for running the simulation -model. - -**Gradle** -```groovy -compile 'com.atlarge.odcsim:odcsim-core:2.0.0' -compile 'com.atlarge.odcsim:odcsim-engine-omega:2.0.0' -``` - -**Maven** -```xml - - com.atlarge.odcsim - odcsim-core - 2.0.0 - - - - com.atlarge.odcsim - odcsim-engine-omega - 2.0.0 - -``` - -### Construction of Simulation Model -Let's construct a simple simulation model of a single car actor. -The car will alternately drive and park for a while. When it starts -driving (or parking), it will print the current simulation time. - - -```kotlin -import com.atlarge.odcsim.Behavior -import com.atlarge.odcsim.coroutines.suspending -import com.atlarge.odcsim.coroutines.dsl.timeout - -fun car(): Behavior = - suspending { ctx -> - while (true) { - println("Start parking at ${ctx.time}") - val parkingDuration = 5.0 - timeout(parkingDuration) - - println("Start driving at ${ctx.time}") - val tripDuration = 2.0 - timeout(tripDuration) - } - - stopped() - } -``` - -### Running Simulation -Running the constructed simulation model requires an implementation -of the `ActorSystem` interface provided by one of the `odcsim-engine-*` -packages. The [ServiceLoader](https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html) -class found in the JDK can be used to locate the `ActorSystem` implementation on the classpath. -```kotlin -import com.atlarge.odcsim.ActorSystemFactory -import java.util.ServiceLoader - -val factory = ServiceLoader.load(ActorSystemFactory::class.java).first() -val system = factory(car(), name = "car") -system.run(until = 10.0) -system.terminate() -``` - ## Contributing ### Contributing Guide Read our [contributing guide](CONTRIBUTING.md) to learn about our @@ -113,4 +44,4 @@ development process, how to propose bug fixes and improvements, and how to build and test your changes to the project. ### License -**odcsim** is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). +The OpenDC simulator is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). -- cgit v1.2.3 From 17bb0205c577720ab5137729d619b1f3cc71297e Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Thu, 21 Nov 2019 14:36:02 +0100 Subject: docs: Move odcsim docs to separate directory --- README.md | 33 ++++++++++----------------------- 1 file changed, 10 insertions(+), 23 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b4da4287..d3cae15f 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,11 @@ OpenDC
- OpenDC + OpenDC Simulator +

+Collaborative Datacenter Simulation and Exploration for Everybody +

Build Status @@ -13,29 +16,13 @@ MIT License

-

- Collaborative Datacenter Simulation and Exploration for Everybody -

- ## Introduction -**odcsim** is a framework for discrete event simulation in Kotlin and Java, used -by the [OpenDC](https://opendc.org) project. -Simulations are defined in terms of a hierarchical grouping of actors -and the interactions between these actors -([Actor model](https://en.wikipedia.org/wiki/Actor_model)), using -an API very similar to [Akka Typed](https://doc.akka.io/docs/akka/current/typed/index.html). - -## Documentation -Check out the [Getting Started](#getting-started) section for a quick -overview. -The documentation is located in the [docs/](docs/) directory and is divided as follows: -* [Main Concepts](docs/concepts.md) -* [Building a Model](docs/build.md) -* [Running a Model](docs/run.md) -* [Pre-built Models](docs/models.md) -* [API Reference](https://atlarge-research.github.io/opendc-simulator) -* [Contributing Guide](CONTRIBUTING.md) +This repository hosts the source code and development of the simulation component of the [OpenDC](https://opendc.org) project. This component is responsible for modelling and simulation of datacenters and their components. We have structured the repository into two individual subprojects: +- **[odcsim](/odcsim)** + A framework for discrete event simulation using the [Kotlin](https://kotlinlang.org/) language. +- **[opendc](/opendc)** + A collection of models for simulating clouds, datacenters and their components using the **odcsim** framework. ## Contributing ### Contributing Guide @@ -44,4 +31,4 @@ development process, how to propose bug fixes and improvements, and how to build and test your changes to the project. ### License -The OpenDC simulator is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). +The OpenDC simulator is available under the [MIT license](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). -- cgit v1.2.3 From b593268b50784964c672f8b5aaa857e9b9243634 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 20 Dec 2019 11:26:33 +0100 Subject: Adapt documentation outline and README --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index d3cae15f..68feccc9 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,17 @@ This repository hosts the source code and development of the simulation componen - **[opendc](/opendc)** A collection of models for simulating clouds, datacenters and their components using the **odcsim** framework. +## Documentation +Check out the [Getting Started](#getting-started) section for a quick +overview. +The documentation is located in the [docs/](docs/) directory and is divided as follows: +1. [Toolchain Setup](docs/setup.md) +2. [Architecture Overview](docs/architecture.md) +3. [Pre-built Models](docs/models.md) +4. [Running a Model](docs/run.md) +5. [Building Your Own Model](docs/build.md) +6. [API Reference](https://atlarge-research.github.io/opendc-simulator) **(TODO maybe remove this until we have created this - see #36)** + ## Contributing ### Contributing Guide Read our [contributing guide](CONTRIBUTING.md) to learn about our -- cgit v1.2.3 From f33cfe79358c31cc786fdb1594cb1c40ab8e0a7b Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 14 Feb 2020 11:37:32 +0100 Subject: Get first two parts of docs up to date and remove odcsim doc --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 68feccc9..1bc866cf 100644 --- a/README.md +++ b/README.md @@ -27,18 +27,19 @@ This repository hosts the source code and development of the simulation componen ## Documentation Check out the [Getting Started](#getting-started) section for a quick overview. -The documentation is located in the [docs/](docs/) directory and is divided as follows: +The documentation is located in the [docs/](docs) directory and is divided as follows: +1. [Introduction](docs/introduction.md) 1. [Toolchain Setup](docs/setup.md) 2. [Architecture Overview](docs/architecture.md) -3. [Pre-built Models](docs/models.md) -4. [Running a Model](docs/run.md) -5. [Building Your Own Model](docs/build.md) -6. [API Reference](https://atlarge-research.github.io/opendc-simulator) **(TODO maybe remove this until we have created this - see #36)** +3. [Running an Experiment](docs/run.md) + +## Getting Started +TODO ## Contributing ### Contributing Guide Read our [contributing guide](CONTRIBUTING.md) to learn about our -development process, how to propose bug fixes and improvements, and how +development process, how to propose bug fixes and improvements, and how to build and test your changes to the project. ### License -- cgit v1.2.3 From bae760a62fc6a480fbe615dff6a7de03c7fd6d1d Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Wed, 24 Jun 2020 09:13:09 +0200 Subject: Add formatter --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 6f66b6af..fbf6f913 100644 --- a/README.md +++ b/README.md @@ -120,3 +120,9 @@ python main.py config.json To try a different query, use the Postman `Builder` to edit the method, path, body, query parameters, etc. `Create New Simulation` is provided as an additional example. When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. + +To format all files, run the following command: + +```bash +yapf **/*.py -i +``` -- cgit v1.2.3 From db979d36d0b9693cc81ffa0bdd29364c6218fc95 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Wed, 24 Jun 2020 13:26:56 +0200 Subject: Add working test setup --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index fbf6f913..cd8bd956 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,4 @@ To try a different query, use the Postman `Builder` to edit the method, path, bo When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. -To format all files, run the following command: - -```bash -yapf **/*.py -i -``` +To format all files, run `format.sh` in this directory. -- cgit v1.2.3 From a1782de1037dc1f818c45257d978da888e87ff85 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Wed, 24 Jun 2020 14:22:58 +0200 Subject: Improve mocking logic --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index cd8bd956..04146f59 100644 --- a/README.md +++ b/README.md @@ -121,4 +121,10 @@ To try a different query, use the Postman `Builder` to edit the method, path, bo When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. +#### Code Style + To format all files, run `format.sh` in this directory. + +#### Testing + +Run `pytest` in this directory to run all tests. -- cgit v1.2.3 From 90fae26aa4bd0e0eb3272ff6e6524060e9004fbb Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 29 Jun 2020 15:47:09 +0200 Subject: Prepare frontend repository for monorepo This change prepares the frontend Git repository for the monorepo residing at https://github.com/atlarge-research.com/opendc. To accomodate for this, we move all files into a frontend subdirectory. --- README.md | 102 -------------------------------------------------------------- 1 file changed, 102 deletions(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index 44858b69..00000000 --- a/README.md +++ /dev/null @@ -1,102 +0,0 @@ -

- OpenDC -
- OpenDC Frontend -

-

- Collaborative Datacenter Simulation and Exploration for Everybody -

- -

- Build Status - License: MIT - styled with prettier
-

- -The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of `create-react-app`. - - -## Get Up and Running - -Looking for the full OpenDC stack? Check out [the main OpenDC repo](https://github.com/atlarge-research/opendc) for instructions on how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually. - -### Installation - -To get started, you'll need the [Node.js environment](https://nodejs.org) and the [Yarn package manager](https://yarnpkg.com). Once you have those installed, run the following command from the root directory of this repo: - -```bash -yarn -``` - -### Running the development server - -First, you need to have a Google OAuth client ID set up. Check the [documentation of the main OpenDC repo](https://github.com/atlarge-research/opendc) if you're not sure how to do this. Once you have such an ID, you need to set it as environment variable `REACT_APP_OAUTH_CLIENT_ID`. One way of doing this is to create an `.env` file with content `REACT_APP_OAUTH_CLIENT_ID=YOUR_ID` (`YOUR_ID` without quotes), in the root directory of this repo. - -Once you've set this variable, you're ready to start the development server: - -```bash -yarn start -``` - -This will start a development server running on [`localhost:3000`](http://localhost:3000), watching for changes you make to the code and rebuilding automatically when you save changes. - -To compile everything for camera-ready deployment, use the following command: - -```bash -yarn build -``` - -**Note:** Perhaps this goes without saying, but for any functionality beyond visiting the entry page, a server backend running in the background is necessary. The easiest way to do this is to have an OpenDC docker container running, see [the main repo](https://github.com/atlarge-research/opendc) for more information on how to do this. - - -## Architecture - -The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while dynamic components and their styles are contained in `src`. The app uses client-side routing (with `react-router`), meaning that the only HTML file needed to be served is a `index.html` file. - -### Pages - -All pages are represented by a component in the `src/pages` directory. There are components for the following pages: - -**Home.js** - Entry page (`/`) - -**Simulations.js** - Overview of simulations of the user (`/simulations`) - -**App.js** - Main application, with datacenter construction and simulation UI (`/simulations/:simulationId` and `/simulations/:simulationId/experiments/:experimentId`) - -**Experiments.js** - Overview of experiments of the current simulation (`/simulations/:simulationId/experiments`) - -**Profile.js** - Profile of the current user (`/profile`) - -**NotFound.js** - 404 page to appear when the route is invalid (`/*`) - -### Components & Containers - -The building blocks of the UI are divided into so-called *components* and *containers* ([as encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of Redux). *Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, are wrappers around *components*, injecting state through the properties of the components they wrap. - -Even the canvas (the main component of the app) is built using React components, with the help of the `react-konva` module. To illustrate: A rectangular object on the canvas is defined in a way that is not very different from how we define a standard `div` element on the splashpage. - -### State Management - -Almost all state is kept in a central Redux store. State is kept there in an immutable form, only to be modified through actions being dispatched. These actions are contained in the `src/actions` folder, and the reducers (managing how state is updated according to dispatched actions) are located in `src/reducers`. If you're not familiar with the Redux approach to state management, have a look at their [official documentation](http://redux.js.org/). - -### API Interaction - -The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API fetch procedures are written with the help of `redux-saga`. The [official documentation](https://redux-saga.js.org/) of `redux-saga` can be a helpful aid in understanding that part of the codebase. - - -## Tests - -Files containing tests can be recognized by the `.test.js` suffix. They are usually located right next to the source code they are testing, to make discovery easier. - -### Running all tests - -The following command runs all tests in the codebase. On top of this, it also watches the code for changes and reruns the tests whenever any file is saved. - -```bash -yarn test -``` - - -## License - -The code is released under the MIT license. See `LICENSE.md`. -- cgit v1.2.3 From 46b06fb446e79c390c01953d31d700b8e73da24d Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 29 Jun 2020 16:04:57 +0200 Subject: Prepare simulator repository for monorepo This change prepares the simulator Git repository for the monorepo residing at https://github.com/atlarge-research.com/opendc. To accomodate for this, we move all files into a simulator subdirectory. --- README.md | 46 ---------------------------------------------- 1 file changed, 46 deletions(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index 1bc866cf..00000000 --- a/README.md +++ /dev/null @@ -1,46 +0,0 @@ -

- - OpenDC - -
- OpenDC Simulator -

-

-Collaborative Datacenter Simulation and Exploration for Everybody -

-

- - Build Status - - - MIT License - -

- -## Introduction -This repository hosts the source code and development of the simulation component of the [OpenDC](https://opendc.org) project. This component is responsible for modelling and simulation of datacenters and their components. We have structured the repository into two individual subprojects: -- **[odcsim](/odcsim)** - A framework for discrete event simulation using the [Kotlin](https://kotlinlang.org/) language. -- **[opendc](/opendc)** - A collection of models for simulating clouds, datacenters and their components using the **odcsim** framework. - -## Documentation -Check out the [Getting Started](#getting-started) section for a quick -overview. -The documentation is located in the [docs/](docs) directory and is divided as follows: -1. [Introduction](docs/introduction.md) -1. [Toolchain Setup](docs/setup.md) -2. [Architecture Overview](docs/architecture.md) -3. [Running an Experiment](docs/run.md) - -## Getting Started -TODO - -## Contributing -### Contributing Guide -Read our [contributing guide](CONTRIBUTING.md) to learn about our -development process, how to propose bug fixes and improvements, and how -to build and test your changes to the project. - -### License -The OpenDC simulator is available under the [MIT license](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). -- cgit v1.2.3 From 4f9a40abdc7836345113c047f27fcc96800cb3f5 Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Mon, 29 Jun 2020 16:05:23 +0200 Subject: Prepare web-server repository for monorepo This change prepares the web-server Git repository for the monorepo residing at https://github.com/atlarge-research.com/opendc. To accomodate for this, we move all files into a web-server subdirectory. --- README.md | 130 -------------------------------------------------------------- 1 file changed, 130 deletions(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index 04146f59..00000000 --- a/README.md +++ /dev/null @@ -1,130 +0,0 @@ -

- OpenDC -
- OpenDC Web Server -

-

-Collaborative Datacenter Simulation and Exploration for Everybody -

- -The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](https://github.com/atlarge-research/opendc/blob/master/opendc-api-spec.json). - -This document explains a high-level view of the web server architecture ([jump](#architecture)), and describes how to set up the web server for local development ([jump](#setup-for-local-development)). - -## Architecture - -The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow. - -![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png) - -The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package. - -### Util Package - -The `Util` package handles several miscellaneous tasks: - -* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`. -* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed. -* `Exceptions`: Holds definitions for exceptions used throughout the web server. -* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database. - -### API Package - -The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`). - -An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model. - -The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it. - -### Models Package - -The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods. - -`Endpoint`s import these `Models` and use them to execute requests. - -## Setup for Local Development - -The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10. - -### Local Setup - -#### Install requirements - -Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements. - -```bash -python setup.py install -``` - -The web server also requires MariaDB >= 10.1. Instructions to install MariaDB can be found [here](https://mariadb.com/kb/en/mariadb/getting-installing-and-upgrading-mariadb/). The Docker image can be found [here](https://hub.docker.com/_/mariadb/). - -#### Get the code - -Clone both this repository and the main OpenDC repository, from the same base directory. - -```bash -git clone https://github.com/atlarge-research/opendc-web-server.git -git clone https://github.com/atlarge-research/opendc.git -``` - -#### Set up the database - -The database can be rebuilt by using the `schema.sql` file from main opendc repository. - -#### Configure OpenDC - -Create a file `config.json` in `opendc-web-server`, containing: - -```json -{ - "ROOT_DIR": "BASE_DIRECTORY", - "OAUTH_CLIENT_ID": "OAUTH_CLIENT_ID", - "FLASK_SECRET": "FLASK_SECRET", - "MYSQL_DATABASE": "opendc", - "MYSQL_USER": "opendc", - "MYSQL_PASSWORD": "opendcpassword", - "MYSQL_HOST": "127.0.0.1", - "MYSQL_PORT": 3306 -} -``` - -Make the following replacements: -* Replace `BASE_DIRECTORY` with the base directory in which you cloned `opendc` and `opendc-web-server`. -* Replace `OAUTH_CLIENT_ID` with your OAuth client ID (see the [OpenDC README](https://github.com/atlarge-research/opendc#preamble)). -* Replace `FLASK_SECRET`, come up with some string. -* Replace the `MYSQL_*` variables with the correct settings for accessing the MariaDB database that was just created. - -In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=` on line `2`. - -#### Set up Postman and OpenDC account - -To easily make HTTP requests to the web server, we recommend Postman (get it [here](https://www.getpostman.com/)). - -Once Postman is installed and set up, `Import` the OpenDC requests collection (`OpenDC.postman_collection.json`). In the `Collections` tab, expand `OpenDC` and click `Create New User`. This should open the request in the `Builder` pane. - -Navigate to `http://localhost:8081/my-auth-token` and copy the authentication token on this page to your clipboard. In the Postman `Builder` pane, navigate to the `Headers (2)` tab, and paste the authentication token as value for the `auth-token` header. (This token expires every hour - refresh the auth token page to get a new token.) - -(Optional: navigate to the `Body` tab and change the email address to the gmail address you used to get an authentication token.) - -Click `Send` in Postman to send your request and see the server's response. If it's a `200`, your account is set up! - -### Local Development - -Run the server. - -```bash -cd opendc-web-server -python main.py config.json -``` - -To try a different query, use the Postman `Builder` to edit the method, path, body, query parameters, etc. `Create New Simulation` is provided as an additional example. - -When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes. - -#### Code Style - -To format all files, run `format.sh` in this directory. - -#### Testing - -Run `pytest` in this directory to run all tests. -- cgit v1.2.3