From fdc3200ef4718eb98bd8a713f956222a9bf85ac9 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Thu, 4 Aug 2022 16:40:44 +0200 Subject: docs: Add initial version of Docusaurus based docs This change updates the repository with a new Docusaurus-based documentation website. This allows us to create our documentation using Markdown, MDX and React. This will serve as the main entry point for users visiting https://opendc.org. The actual OpenDC application will be moved to https://app.opendc.org. --- docs/architecture.md | 21 --------- docs/deploy.md | 80 -------------------------------- docs/images/component-diagram.png | Bin 39965 -> 0 bytes docs/images/logo.png | Bin 2825 -> 0 bytes docs/images/screenshot-construction.png | Bin 275103 -> 0 bytes docs/images/screenshot-simulation.png | Bin 291836 -> 0 bytes docs/research.md | 41 ---------------- docs/toolchain.md | 70 ---------------------------- 8 files changed, 212 deletions(-) delete mode 100644 docs/architecture.md delete mode 100644 docs/deploy.md delete mode 100644 docs/images/component-diagram.png delete mode 100644 docs/images/logo.png delete mode 100644 docs/images/screenshot-construction.png delete mode 100644 docs/images/screenshot-simulation.png delete mode 100644 docs/research.md delete mode 100644 docs/toolchain.md (limited to 'docs') diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index c4609ae9..00000000 --- a/docs/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Architecture - -OpenDC consists of four components: a Kotlin simulator, a SQL database, a Quarkus-based -[API](/opendc-web/opendc-web-api), and a React.js [frontend](/opendc-web/opendc-web-ui). - -![OpenDC Component Diagram](./images/component-diagram.png) - -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 via a REST -API over 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 [API spec](https://api.opendc.org/q/openapi). - -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 `PENDING`. - -The simulator monitors the database for `PENDING` 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 deleted file mode 100644 index ac417def..00000000 --- a/docs/deploy.md +++ /dev/null @@ -1,80 +0,0 @@ -# Deploying OpenDC -This document explains how you can deploy a multi-tenant instance of OpenDC using Docker. - -## Contents - -1. [Setting up Auth0](#setting-up-auth0) -1. [Installing Docker](#installing-docker) -1. [Running OpenDC from source](#running-opendc-from-source) - -## Setting up Auth0 - -OpenDC uses [Auth0](https://auth0.com) as Identity Provider so that OpenDC does not have to manage user data itself, -which greatly simplifies our frontend and backend implementation. We have chosen to use Auth0 as it is a well-known -Identity Provider with good software support and a free tier for users to experiment with. - -To deploy OpenDC yourself, you need to have an [Auth0 tenant](https://auth0.com/docs/get-started/learn-the-basics) and -create: - -1. **An API** - You need to define the OpenDC API server in Auth0. Please refer to the [following guide](https://auth0.com/docs/quickstart/backend/python/01-authorization#create-an-api) - on how to define an API in Auth0. - - Remember the identifier you created the API with, as we need it in the next steps (as `OPENDC_AUTH0_AUDIENCE`). -2. **A Single Page Application (SPA)** - You need to define the OpenDC frontend application in Auth0. Please see the [following guide](https://auth0.com/docs/quickstart/spa/react#configure-auth0) - on how you can define an SPA in Auth0. Make sure you have added the necessary URLs to the _Allowed Callback URLs_: - for a local deployment, you should add at least `http://localhost:3000, http://localhost:8080`. - - Once your application has been created, you should have a _Domain_ and _Client ID_ which we need to pass to the - frontend application (as `OPENDC_AUTH0_DOMAIN` and `OPENDC_AUTH0_CLIENT_ID` respectively). - - -## 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 from source - -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-auth0-*` with the Auth0 details you got from the first -step. For a standard setup, you can leave the other settings as-is. - -```.env -OPENDC_DB_USERNAME=opendc -OPENDC_DB_PASSWORD=opendcpassword -OPENDC_AUTH0_DOMAIN=your-auth0-domain -OPENDC_AUTH0_CLIENT_ID=your-auth0-client-id -OPENDC_AUTH0_AUDIENCE=your-auth0-api-identifier -OPENDC_API_BASE_URL=http://web -``` - -We provide a set 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 SQL init script](../opendc-web/opendc-web-server/src/main/resources/db/migration/V1.0.0__core.sql)) - -If you plan to deploy publicly, please also tweak the other settings. In that case, also check the `docker-compose.yml` -and `docker-compose.prod.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 user experience. diff --git a/docs/images/component-diagram.png b/docs/images/component-diagram.png deleted file mode 100644 index 312ca72a..00000000 Binary files a/docs/images/component-diagram.png and /dev/null differ diff --git a/docs/images/logo.png b/docs/images/logo.png deleted file mode 100644 index d743038b..00000000 Binary files a/docs/images/logo.png and /dev/null differ diff --git a/docs/images/screenshot-construction.png b/docs/images/screenshot-construction.png deleted file mode 100644 index ea20a7c4..00000000 Binary files a/docs/images/screenshot-construction.png and /dev/null differ diff --git a/docs/images/screenshot-simulation.png b/docs/images/screenshot-simulation.png deleted file mode 100644 index 1bd989c7..00000000 Binary files a/docs/images/screenshot-simulation.png and /dev/null differ diff --git a/docs/research.md b/docs/research.md deleted file mode 100644 index f9830e8e..00000000 --- a/docs/research.md +++ /dev/null @@ -1,41 +0,0 @@ -## 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. [Modeling and Simulation of the Google TensorFlow Ecosystem](https://atlarge-research.com/pdfs/lai2020thesis.pdf) - **Master Thesis, 2020** - Wenchen Lai -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](https://atlarge-research.com/pdfs/BSc-Thesis-JACOB_BURLEY_FINAL.pdf) - **Bachelor Thesis, 2020** - Jacob Burley -1. [A Trace-Based Validation Study of OpenDC](https://atlarge-research.com/pdfs/2020-12-02_bsc_thesis_jaro_final.pdf) - **Bachelor Thesis, 2020** - Jaro Bosch -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 deleted file mode 100644 index 016c8201..00000000 --- a/docs/toolchain.md +++ /dev/null @@ -1,70 +0,0 @@ -# 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) -2. [Building and Developing](#2-building-and-developing) -3. [Setup with IntelliJ IDEA](#21-setup-with-intellij-idea) -4. [Setup with Command Line](#22-setup-with-command-line) - -## 1. Installing Java - -OpenDC requires a Java installation of version 11 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! -- cgit v1.2.3