diff options
| author | Fabian Mastenbroek <mail.fabianm@gmail.com> | 2021-05-03 21:12:00 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-05-03 21:12:00 +0200 |
| commit | 17ffe995ee06d5755cd3943a5ea14f982884009e (patch) | |
| tree | 2f360f1974bdbfd5f7fcd3d8e9c142b28650d7ed | |
| parent | c3ee3cb899d5259c619e79ff9f29984756c3813e (diff) | |
| parent | f081b9cab58a31a55c4f9dc6ccedd8cb92fc9242 (diff) | |
Prepare for OpenDC 2.0 release (v1)
This pull request performs several preparations for the official release of OpenDC 2.0.
This pull request mostly focuses on documentation changes.
## Details
1. Restructure project documentation
2. Migrate to Dokka 1.4.32
3. Merge CI builds into single workflow
22 files changed, 422 insertions, 231 deletions
diff --git a/.github/workflows/build-api.yml b/.github/workflows/build-api.yml deleted file mode 100644 index e863ba05..00000000 --- a/.github/workflows/build-api.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: Build API - -on: - pull_request: - branches: [master] - -defaults: - run: - working-directory: opendc-web/opendc-web-api - -jobs: - build: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest] - python: [3.8] - steps: - - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: ${{ matrix.python }} - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - - name: Lint with pylint - run: ./check.sh - - name: Test with pytest - run: pytest --cov=opendc/ --junitxml=.junit-report.xml - - name: Publish report - if: always() - uses: mikepenz/action-junit-report@v2 - with: - check_name: test (Python ${{ matrix.python }}) - report_paths: '**/.junit-report.xml' - github_token: ${{ secrets.GITHUB_TOKEN }} - - name: Upload code coverage - uses: codecov/codecov-action@v1 - with: - token: ${{ secrets.CODECOV_TOKEN }} - files: opendc-web/opendc-web-api/.coverage - flags: api - diff --git a/.github/workflows/build-frontend.yml b/.github/workflows/build-frontend.yml deleted file mode 100644 index e00340ed..00000000 --- a/.github/workflows/build-frontend.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: Build Frontend - -on: - pull_request: - branches: [master] - -defaults: - run: - working-directory: opendc-web/opendc-web-ui - -jobs: - build: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest] - node: [14.x] - steps: - - uses: actions/checkout@v2 - - name: Set up Node.js - uses: actions/setup-node@v1 - with: - node-version: ${{ matrix.node }} - - run: npm install - - run: npm run build --if-present - - run: npm test - env: - CI: true diff --git a/.github/workflows/build-simulator.yml b/.github/workflows/build-simulator.yml deleted file mode 100644 index ee8f95f2..00000000 --- a/.github/workflows/build-simulator.yml +++ /dev/null @@ -1,56 +0,0 @@ -name: Build Simulator - -on: - pull_request: - branches: [master] - -jobs: - build: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest] - java: [8, 15] - steps: - - name: Checkout repository - uses: actions/checkout@v2 - - name: Validate Gradle wrapper - uses: gradle/wrapper-validation-action@v1 - - name: Set up JDK - uses: actions/setup-java@v1 - with: - java-version: ${{ matrix.java }} - - name: Grant execute permission for gradlew - run: chmod +x gradlew - - uses: actions/cache@v1 - with: - path: ~/.gradle/caches - key: ${{ runner.os }}-${{ matrix.java }}-gradle-${{ hashFiles('**/*.gradle*') }} - restore-keys: | - ${{ runner.os }}-${{ matrix.java }}-gradle- - - name: Build with Gradle - run: ./gradlew assemble - - name: Check with Gradle - run: ./gradlew check codeCoverageReport - - name: Publish report - if: always() - uses: mikepenz/action-junit-report@v2 - with: - check_name: test (Java ${{ matrix.java }}) - report_paths: '**/build/test-results/test/TEST-*.xml' - github_token: ${{ secrets.GITHUB_TOKEN }} - - name: Upload artifacts - if: always() - uses: actions/upload-artifact@v2 - with: - name: reports-${{ matrix.os }}-jdk${{ matrix.java }} - path: | - ./**/build/reports/**/* - ./**/build/test-results/**/* - retention-days: 5 - - name: Upload code coverage - uses: codecov/codecov-action@v1 - with: - token: ${{ secrets.CODECOV_TOKEN }} - files: ./build/reports/jacoco/report.xml - flags: simulator diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 00000000..cbf2f80d --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,115 @@ +name: Build + +on: + pull_request: + branches: [master] + +jobs: + build-simulator: + name: Build Simulator (Java ${{ matrix.java }}) + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] + java: [8, 15] + steps: + - name: Checkout repository + uses: actions/checkout@v2 + - name: Validate Gradle wrapper + uses: gradle/wrapper-validation-action@v1 + - name: Set up JDK + uses: actions/setup-java@v1 + with: + java-version: ${{ matrix.java }} + - name: Grant execute permission for gradlew + run: chmod +x gradlew + - uses: actions/cache@v1 + with: + path: ~/.gradle/caches + key: ${{ runner.os }}-${{ matrix.java }}-gradle-${{ hashFiles('**/*.gradle*') }} + restore-keys: | + ${{ runner.os }}-${{ matrix.java }}-gradle- + - name: Build with Gradle + run: ./gradlew assemble + - name: Check with Gradle + run: ./gradlew check codeCoverageReport + - name: Publish report + if: always() + uses: mikepenz/action-junit-report@v2 + with: + check_name: test (Java ${{ matrix.java }}) + report_paths: '**/build/test-results/test/TEST-*.xml' + github_token: ${{ secrets.GITHUB_TOKEN }} + - name: Upload artifacts + if: always() + uses: actions/upload-artifact@v2 + with: + name: reports-${{ matrix.os }}-jdk${{ matrix.java }} + path: | + ./**/build/reports/**/* + ./**/build/test-results/**/* + retention-days: 5 + - name: Upload code coverage + uses: codecov/codecov-action@v1 + with: + token: ${{ secrets.CODECOV_TOKEN }} + files: ./build/reports/jacoco/report.xml + flags: simulator + build-api: + name: Build API (Python ${{ matrix.python }}) + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] + python: [3.8] + defaults: + run: + working-directory: opendc-web/opendc-web-api + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + - name: Lint with pylint + run: ./check.sh + - name: Test with pytest + run: pytest --cov=opendc/ --junitxml=.junit-report.xml + - name: Publish report + if: always() + uses: mikepenz/action-junit-report@v2 + with: + check_name: test (Python ${{ matrix.python }}) + report_paths: '**/.junit-report.xml' + github_token: ${{ secrets.GITHUB_TOKEN }} + - name: Upload code coverage + uses: codecov/codecov-action@v1 + with: + token: ${{ secrets.CODECOV_TOKEN }} + files: opendc-web/opendc-web-api/.coverage + flags: api + build-ui: + name: Build UI (Node ${{ matrix.node }}) + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] + node: [14.x] + defaults: + run: + working-directory: opendc-web/opendc-web-ui + steps: + - uses: actions/checkout@v2 + - name: Set up Node.js + uses: actions/setup-node@v1 + with: + node-version: ${{ matrix.node }} + - run: npm install + - run: npm run build --if-present + - run: npm test + env: + CI: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ed01f8a..e4109272 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,26 @@ # Contributing to OpenDC -First of all, thanks for wanting to contribute! 🎉 - +First of all, thank you for wanting to contribute to OpenDC! 🎉 ## 💬 Have a question or general feedback relating to OpenDC? Contact us at 📧[opendc@atlarge-research.com](mailto:opendc@atlarge-research.com)! - ## 🐞 Want to report a bug or suggest a feature? -Please file an issue! First, have a look if someone has already filed an issue addressing your concern. If there already is such an issue, feel free to comment on the issue to show your support for it, or to add additional information that might be helpful. You can also just react with a thumbs-up 👍 to the issue, to indicate that you'd be interested in its resolution. This can help us prioritize what we spend our development time on. - -If you can't find an issue that fits your problem or feature request, open a new one. Describe actual and expected behavior, and be as detailed as you can. We'll get back to you asap! +Please file an issue! First, have a look if someone has already filed an issue addressing your concern. If there already +is such an issue, feel free to comment on the issue to show your support for it, or to add additional information that +might be helpful. You can also just react with a thumbs-up 👍 to the issue, to indicate that you'd be interested in its +resolution. This can help us prioritize what we spend our development time on. +If you can't find an issue that fits your problem or feature request, open a new one. Describe actual and expected +behavior, and be as detailed as you can. We'll get back to you asap! ## 💻 Want to contribute code? -That's great! If you want to contribute to this repository, [fork it](https://github.com/atlarge-research/opendc/new/master) and submit a PR here when you're ready! Be sure to describe *what* you changed and *why* you changed it, to help us understand what your contribution is about. +That's great! If you want to contribute to this +repository, [fork it](https://github.com/atlarge-research/opendc/new/master) and submit a PR here when you're ready! Be +sure to describe *what* you changed and *why* you changed it, to help us understand what your contribution is about. -A quick note on commit messages: Please follow common Git standards when writing commit messages, see [this post](https://chris.beams.io/posts/git-commit/) for details. +A quick note on commit messages: Please follow common Git standards when writing commit messages, +see [this post](https://chris.beams.io/posts/git-commit/) for details. @@ -1,104 +1,56 @@ -<h1 align="center"> - <img src="https://raw.githubusercontent.com/atlarge-research/opendc/master/misc/artwork/logo.png" width="100" alt="OpenDC"> - <br> - OpenDC -</h1> -<p align="center"> - Collaborative Datacenter Simulation and Exploration for Everybody -</p> +<a href="https://opendc.org/"> + <img src="https://opendc.org/img/logo.png" alt="OpenDC logo" title="OpenDC" align="right" height="100" /> +</a> -<br> +# OpenDC -OpenDC is an open-source simulator for datacenters aimed at both research and education. +Collaborative Datacenter Simulation and Exploration for Everybody - +[](/LICENSE.txt) +[](./docs) +[](https://github.com/atlarge-research/opendc/releases) +[](https://github.com/atlarge-research/opendc/actions/workflows/build.yml) -Users can construct datacenters (see above) and define portfolios of scenarios (experiments) to see how these datacenters perform under different workloads and schedulers (see below). +----- - +OpenDC is a free and open-source platform for datacenter simulation aimed at both research and education. -The simulator is accessible both as a ready-to-use website hosted by us at [opendc.org](https://opendc.org), and as source code that users can run locally on their own machine, through Docker. + -🛠 OpenDC is a project by the [@Large Research Group](https://atlarge-research.com). - -🐟 OpenDC comes bundled with [Capelin](https://repository.tudelft.nl/islandora/object/uuid:d6d50861-86a3-4dd3-a13f-42d84db7af66?collection=education), the capacity planning tool for cloud datacenters based on portfolios of what-if scenarios. More information on how to use and extend Capelin coming soon! - -## Architecture - -OpenDC consists of four components: a Kotlin simulator, a MongoDB database, a Python Flask [API](/opendc-web/opendc-web-api), and a React.js [frontend](/opendc-web/opendc-web-ui). - -<p align="center"> - <img src="https://raw.githubusercontent.com/atlarge-research/opendc/master/misc/artwork/opendc-component-diagram.png" alt="OpenDC Component Diagram"> -</p> - -On the frontend, users can construct a topology by specifying a datacenter's rooms, racks and machines, and create scenarios to see how a workload trace runs on that topology. The frontend communicates with the web server over SocketIO, through a custom REST request/response layer. For example, the frontend might make a `GET` request to `/api/v1/users/{userId}`, but this request is completed via SocketIO, not plain HTTP requests. Note that the API itself can also be accessed by HTTP. - -The (Swagger/OpenAPI compliant) API spec specifies what requests the frontend can make to the web server. To view this specification, go to the [Swagger Editor](https://editor.swagger.io/) and paste in our [opendc-api-spec.yml](opendc-api-spec.yml). - -The web server receives API requests and processes them in the database. When the frontend requests to run a new scenario, the web server adds it to the `scenarios` collection in the database and sets its `state` as `QUEUED`. - -The simulator monitors the database for `QUEUED` scenarios, and simulates them as they are submitted. The results -of the simulations are processed and aggregated in memory. Afterwards, the aggregated summary is written to the database, -which the frontend can then again retrieve via the web server. - -## Setup +Users can construct datacenters (see above) and define portfolios of scenarios (experiments) to see how these +datacenters perform under different workloads and schedulers (see below). -### Preamble + -The official way to run OpenDC is using Docker. Other options include building and running locally, and building and running to deploy on a server. +The simulator is accessible both as a ready-to-use website hosted by us at [opendc.org](https://opendc.org), and as +source code that users can run locally on their own machine, through Docker. -For all of these options, you have to create a Google API Console project and client ID, which the OpenDC frontend and web server will use to authenticate users and requests. Follow [these steps](https://developers.google.com/identity/sign-in/web/sign-in) to make such a project. In the 'Authorized JavaScript origins' and 'Authorized redirect URI' fields, be sure to add `http://localhost:8080` (frontend), `http://localhost:8081` (api) and `https://localhost:3000` (frontend dev). Download the JSON of the OAuth 2.0 client ID you created from the Credentials tab, and specifically note the `client_id`, which you'll need to build OpenDC. +To learn more +about OpenDC, have a look through our paper [OpenDC 2.0](https://atlarge-research.com/pdfs/ccgrid21-opendc-paper.pdf) +or on our [vision](https://atlarge-research.com/pdfs/opendc-vision17ispdc_cr.pdf). -### Installing Docker -OpenDC uses [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) to orchestrate the -deployment of the software stack. Please refer to [Docker Desktop](https://www.docker.com/products/docker-desktop) for -instructions on how install Docker on your machine. - - -### Running OpenDC - -To build and run the full OpenDC stack locally on Linux or Mac, you first need to clone the project: - -```bash -git clone https://github.com/atlarge-research/opendc.git - -# Enter the directory -cd opendc/ -``` - -In the directory you just entered, you need to set up a set of environment variables. -To do this, create a file called `.env` in the `opendc` folder. In this file, -replace `your-google-oauth-client-id` with your `client_id` from the OAuth client ID you created. -For a standard setup, you can leave the other settings as-is. - -```.env -MONGO_INITDB_ROOT_USERNAME=root -MONGO_INITDB_ROOT_PASSWORD=rootpassword -MONGO_INITDB_DATABASE=admin -OPENDC_DB=opendc -OPENDC_DB_USERNAME=opendc -OPENDC_DB_PASSWORD=opendcpassword -OPENDC_FLASK_SECRET="This is a secret flask key, please change" -OPENDC_OAUTH_CLIENT_ID=your-google-oauth-client-id -OPENDC_API_BASE_URL=http://localhost:8081 -``` +🛠 OpenDC is a project by the [@Large Research Group](https://atlarge-research.com). -We provide a list of default traces for you to experiment with. If you want to add others, place them in the `traces` directory and add entries to the database (see also [the database folder](database/mongo-init-opendc-db.sh)) +🐟 OpenDC comes bundled +with [Capelin](https://repository.tudelft.nl/islandora/object/uuid:d6d50861-86a3-4dd3-a13f-42d84db7af66?collection=education) +, the capacity planning tool for cloud datacenters based on portfolios of what-if scenarios. More information on how to +use and extend Capelin coming soon! -If you plan to publicly deploy, please also tweak the other settings. -In that case, also check the `docker-compose.yml` and `docker-compose.pod.yml` for further instructions. +## Documentation -Now, start the server: +The documentation is located in the [docs/](docs) directory and is divided as follows: -```bash -# Build the Docker image -docker-compose build +1. [Deployment Guide](docs/deploy.md) +1. [Architectural Overview](docs/architecture.md) +1. [Toolchain Setup](docs/toolchain.md) +1. [Research with OpenDC](docs/research.md) +1. [Contributing Guide](CONTRIBUTING.md) -# Start the containers -docker-compose up -``` +## Contributing -Wait a few seconds and open `http://localhost:8080` in your browser to use OpenDC. We recommend Google Chrome for the best development experience. +Questions, suggestions and contributions are welcome and appreciated! +Please refer to the [contributing guidelines](CONTRIBUTING.md) for more details. ## License + OpenDC is distributed under the MIT license. See [LICENSE.txt](/LICENSE.txt). diff --git a/build.gradle.kts b/build.gradle.kts index 061d8fc3..a4d02854 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -23,6 +23,7 @@ plugins { `dokka-conventions` `jacoco-aggregation` + `distribution-conventions` } allprojects { diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index dc115999..94d6b19d 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -29,6 +29,11 @@ plugins { /* Project configuration */ repositories { gradlePluginPortal() + maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") { + content { + includeGroup("org.jetbrains.kotlinx") + } + } } dependencies { @@ -37,6 +42,7 @@ dependencies { implementation("org.jetbrains.dokka:dokka-gradle-plugin:0.10.1") implementation("org.jetbrains.kotlin:kotlin-allopen:1.4.31") implementation("org.jetbrains.kotlinx:kotlinx-benchmark-plugin:0.3.0") + implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.4.32") } tasks.withType<KotlinCompile>().configureEach { diff --git a/buildSrc/src/main/kotlin/distribution-conventions.gradle.kts b/buildSrc/src/main/kotlin/distribution-conventions.gradle.kts new file mode 100644 index 00000000..a0b7593d --- /dev/null +++ b/buildSrc/src/main/kotlin/distribution-conventions.gradle.kts @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2021 AtLarge Research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +import org.gradle.api.distribution.DistributionContainer + + +plugins { + distribution +} + +tasks.named("assembleDist") { + val tasks = getTasksByName("assembleDist", true).filter { it.project != project } + dependsOn(tasks) +} + +distributions { + main { + contents { + duplicatesStrategy = DuplicatesStrategy.EXCLUDE + + from("README.md") + from("LICENSE.txt") + + // Include the distributions of the sub project. + getTasksByName("assembleDist", true) + .filter { it.project != project } + .map { it.project.the<DistributionContainer>()["main"] } + .forEach { with(it.contents) } + } + } +} diff --git a/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts b/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts index 91156cbf..1df9a15c 100644 --- a/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts @@ -1,7 +1,5 @@ /* - * MIT License - * - * Copyright (c) 2021 atlarge-research + * Copyright (c) 2021 AtLarge Research * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -22,12 +20,10 @@ * SOFTWARE. */ -import org.jetbrains.dokka.gradle.DokkaTask - plugins { id("org.jetbrains.dokka") } -tasks.getting(DokkaTask::class) { - outputFormat = "html" +repositories { + mavenCentral() } diff --git a/buildSrc/src/main/kotlin/kotlin-library-conventions.gradle.kts b/buildSrc/src/main/kotlin/kotlin-library-conventions.gradle.kts index cf3f2569..43b1d148 100644 --- a/buildSrc/src/main/kotlin/kotlin-library-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/kotlin-library-conventions.gradle.kts @@ -28,6 +28,7 @@ plugins { `java-library` kotlin("jvm") id("org.jlleitschuh.gradle.ktlint") + id("dokka-conventions") } /* Project configuration */ diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..032e8f4b --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,25 @@ +# Architecture + +OpenDC consists of four components: a Kotlin simulator, a MongoDB database, a Python +Flask [API](/opendc-web/opendc-web-api), and a React.js [frontend](/opendc-web/opendc-web-ui). + +<p align="center"> + <img src="https://raw.githubusercontent.com/atlarge-research/opendc/master/misc/artwork/opendc-component-diagram.png" alt="OpenDC Component Diagram"> +</p> + +On the frontend, users can construct a topology by specifying a datacenter's rooms, racks and machines, and create +scenarios to see how a workload trace runs on that topology. The frontend communicates with the web server over +SocketIO, through a custom REST request/response layer. For example, the frontend might make a `GET` request +to `/api/v1/users/{userId}`, but this request is completed via SocketIO, not plain HTTP requests. Note that the API +itself can also be accessed by HTTP. + +The (Swagger/OpenAPI compliant) API spec specifies what requests the frontend can make to the web server. To view this +specification, go to the [Swagger Editor](https://editor.swagger.io/) and paste in +our [opendc-api-spec.yml](../opendc-api-spec.yml). + +The web server receives API requests and processes them in the database. When the frontend requests to run a new +scenario, the web server adds it to the `scenarios` collection in the database and sets its `state` as `QUEUED`. + +The simulator monitors the database for `QUEUED` scenarios, and simulates them as they are submitted. The results of the +simulations are processed and aggregated in memory. Afterwards, the aggregated summary is written to the database, which +the frontend can then again retrieve via the web server. diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 00000000..b9d65d51 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,65 @@ +# Deploying OpenDC + +### Preamble + +The official way to run OpenDC is using Docker. Other options include building and running locally, and building and +running to deploy on a server. + +For all of these options, you have to create a Google API Console project and client ID, which the OpenDC frontend and +web server will use to authenticate users and requests. +Follow [these steps](https://developers.google.com/identity/sign-in/web/sign-in) to make such a project. In the ' +Authorized JavaScript origins' and 'Authorized redirect URI' fields, be sure to add `http://localhost:8080` (frontend) +, `http://localhost:8081` (api) and `https://localhost:3000` (frontend dev). Download the JSON of the OAuth 2.0 client +ID you created from the Credentials tab, and specifically note the `client_id`, which you'll need to build OpenDC. + +### Installing Docker + +OpenDC uses [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) to orchestrate the +deployment of the software stack. Please refer to [Docker Desktop](https://www.docker.com/products/docker-desktop) for +instructions on how install Docker on your machine. + +### Running OpenDC + +To build and run the full OpenDC stack locally on Linux or Mac, you first need to clone the project: + +```bash +git clone https://github.com/atlarge-research/opendc.git + +# Enter the directory +cd opendc/ +``` + +In the directory you just entered, you need to set up a set of environment variables. To do this, create a file +called `.env` in the `opendc` folder. In this file, replace `your-google-oauth-client-id` with your `client_id` from the +OAuth client ID you created. For a standard setup, you can leave the other settings as-is. + +```.env +MONGO_INITDB_ROOT_USERNAME=root +MONGO_INITDB_ROOT_PASSWORD=rootpassword +MONGO_INITDB_DATABASE=admin +OPENDC_DB=opendc +OPENDC_DB_USERNAME=opendc +OPENDC_DB_PASSWORD=opendcpassword +OPENDC_FLASK_SECRET="This is a secret flask key, please change" +OPENDC_OAUTH_CLIENT_ID=your-google-oauth-client-id +OPENDC_API_BASE_URL=http://localhost:8081 +``` + +We provide a list of default traces for you to experiment with. If you want to add others, place them in the `traces` +directory and add entries to the database (see also [the database folder](database/mongo-init-opendc-db.sh)) + +If you plan to publicly deploy, please also tweak the other settings. In that case, also check the `docker-compose.yml` +and `docker-compose.pod.yml` for further instructions. + +Now, start the server: + +```bash +# Build the Docker image +docker-compose build + +# Start the containers +docker-compose up +``` + +Wait a few seconds and open `http://localhost:8080` in your browser to use OpenDC. We recommend Google Chrome for the +best development experience. diff --git a/misc/artwork/logo.png b/docs/images/logo.png Binary files differindex d743038b..d743038b 100644 --- a/misc/artwork/logo.png +++ b/docs/images/logo.png diff --git a/misc/artwork/opendc-component-diagram.png b/docs/images/opendc-component-diagram.png Binary files differindex 312ca72a..312ca72a 100644 --- a/misc/artwork/opendc-component-diagram.png +++ b/docs/images/opendc-component-diagram.png diff --git a/misc/artwork/opendc-frontend-construction.png b/docs/images/opendc-frontend-construction.png Binary files differindex 223e8d48..223e8d48 100644 --- a/misc/artwork/opendc-frontend-construction.png +++ b/docs/images/opendc-frontend-construction.png diff --git a/misc/artwork/opendc-frontend-simulation-zoom.png b/docs/images/opendc-frontend-simulation-zoom.png Binary files differindex d7744926..d7744926 100644 --- a/misc/artwork/opendc-frontend-simulation-zoom.png +++ b/docs/images/opendc-frontend-simulation-zoom.png diff --git a/misc/artwork/opendc-frontend-simulation.png b/docs/images/opendc-frontend-simulation.png Binary files differindex bbf4cbd6..bbf4cbd6 100644 --- a/misc/artwork/opendc-frontend-simulation.png +++ b/docs/images/opendc-frontend-simulation.png diff --git a/docs/research.md b/docs/research.md new file mode 100644 index 00000000..1eeefecf --- /dev/null +++ b/docs/research.md @@ -0,0 +1,35 @@ +## Research with OpenDC + +This document contains publications related to OpenDC or publications that have used OpenDC in their work. + +## Publications about OpenDC + +1. [OpenDC 2.0: Convenient Modeling and Simulation of Emerging Technologies in Cloud Datacenters](https://atlarge-research.com/pdfs/ccgrid21-opendc-paper.pdf) + **CCGrid 2021** + Fabian Mastenbroek, Georgios Andreadis, Soufiane Jounaid, Wenchen Lai, Jacob Burley, Jaro Bosch, Erwin van Eyk, + Laurens Versluis, Vincent van Beek, Alexandru Iosup +1. [The OpenDC vision: Towards collaborative datacenter simulation and exploration for everybody](https://atlarge-research.com/pdfs/opendc-vision17ispdc_cr.pdf) + **ISPDC 2017 (invited paper)** + Alexandru Iosup, Georgios Andreadis, Vincent van Beek, Matthijs Bijman, Erwin van Eyk, Mihai Neacsu, Leon Overweel, + Sacheendra Talluri, Laurens Versluis, Maaike Visser. + +## Publications using OpenDC + +1. [A Reference Architecture for Datacenter Scheduling](https://arxiv.org/pdf/1808.04224) + **International Conference for High Performance Computing, Networking, Storage and Analysis 2018 (SC18)** + Georgios Andreadis, Laurens Versluis, Fabian S. Mastenbroek, Alexandru Iosup + +## Students using OpenDC + +1. [Capelin: Fast Data-Driven Capacity Planning for Cloud Datacenters](https://repository.tudelft.nl/islandora/object/uuid:d6d50861-86a3-4dd3-a13f-42d84db7af66?collection=education) + **Master Thesis, 2020** + Georgios Andreadis +1. [OpenDC Serverless: Design, Implementation and Evaluation of a FaaS Platform Simulator](https://zenodo.org/record/4046675) + **Bachelor Thesis, 2020** + Soufiane Jounaid +1. LEGO, but with Servers: Creating the Building Blocks to Design and Simulate Datacenters + **Bachelor Thesis, 2020** + Jacob Burley +1. [A Systematic Design Space Exploration of Datacenter Schedulers](https://repository.tudelft.nl/islandora/object/uuid%3A20478016-cc7d-4c87-aa12-25b46f511277?collection=education) + **Bachelor Thesis, 2019** + Fabian S. Mastenbroek diff --git a/docs/toolchain.md b/docs/toolchain.md new file mode 100644 index 00000000..4b029ebc --- /dev/null +++ b/docs/toolchain.md @@ -0,0 +1,70 @@ +# Toolchain Setup + +The OpenDC simulator is built using the [Kotlin](https://kotlinlang.org/) language. This is a JVM-based language that +should appear familiar to programmers knowledgeable in Java or Scala. For a short interactive introduction to Kotlin, +the [Learn Kotlin By Example](https://play.kotlinlang.org/byExample/overview) docs are a great place to start. + +For the build and dependency toolchain, we use [Gradle](https://gradle.org/). You will likely not need to change the +Gradle build configurations of components, but you will use Gradle to execute builds and tests on the codebase. + +Follow the steps below to get it all set up! + +## Contents + +1. [Installing Java](#1-installing-java) +1. [Building and Developing](#2-building-and-developing) + 1. [Setup with IntelliJ IDEA](#21-setup-with-intellij-idea) + 1. [Setup with Command Line](#22-setup-with-command-line) + +## 1. Installing Java + +Kotlin requires a Java installation of version 8 or higher. Make sure to install +the [JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html), not only the JRE (the JDK also includes +a JRE). + +## 2. Building and Developing + +With Java installed, we're ready to set up the development environment on your machine. You can either use a visual IDE +or work from a command line shell. We outline both approaches below, feel free to choose which you are most comfortable +with. If in doubt which one to choose, we suggest going with the first one. + +## 2.1 Setup with IntelliJ IDEA + +We suggest using [IntelliJ IDEA](https://www.jetbrains.com/idea/) as development environment. Once you have installed +any version of this IDE on your machine, choose "Get from Version Control" in the new project dialogue. +Enter `https://github.com/atlarge-research/opendc` as URL and submit your credentials when asked. +Open the project once it's ready fetching the codebase, and let it set up with the defaults (IntelliJ will recognize +that this is a Gradle codebase). + +You will now be prompted in a dialogue to enable auto-import for Gradle, which we suggest you do. Wait for any progress +bars in the lower bar to disappear and then look for the Gradle context menu on the right-hand side. In it, go +to `opendc > Tasks > verification > test`. This will build the codebase and run checks to verify that tests +pass. If you get a `BUILD SUCCESSFUL` message, you're ready to go to the [next section](architecture.md)! + +## 2.2 Setup with Command Line + +First, clone the repository with the following command: + +```shell script +git clone https://github.com/atlarge-research/opendc +``` + +And enter the directory: + +```shell script +cd opendc +``` + +If on Windows, run the batch file included in the root, as follows: + +```commandline +gradlew.bat test +``` + +If on Linux/macOS, run the shell script included in the root, as follows: + +```shell script +./gradlew test +``` + +If the build is successful, you are ready to go to the next section! diff --git a/opendc-web/opendc-web-api/README.md b/opendc-web/opendc-web-api/README.md index 182cd803..4932f823 100644 --- a/opendc-web/opendc-web-api/README.md +++ b/opendc-web/opendc-web-api/README.md @@ -1,5 +1,5 @@ <h1 align="center"> - <img src="../misc/artwork/logo.png" width="100" alt="OpenDC"> + <img src="../../docs/images/logo.png" width="100" alt="OpenDC"> <br> OpenDC Web Server </h1> @@ -9,7 +9,7 @@ <br> -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](../opendc-api-spec.yml). +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](../../opendc-api-spec.yml). 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)). diff --git a/opendc-web/opendc-web-ui/README.md b/opendc-web/opendc-web-ui/README.md index ae556b09..f3a58e7a 100644 --- a/opendc-web/opendc-web-ui/README.md +++ b/opendc-web/opendc-web-ui/README.md @@ -1,5 +1,5 @@ <h1 align="center"> - <img src="../misc/artwork/logo.png" width="100" alt="OpenDC"> + <img src="../../docs/images/logo.png" width="100" alt="OpenDC"> <br> OpenDC Frontend </h1> |
