merge: Add documentation using Docusaurus (#97)

This pull request implements the new OpenDC documentation website using Docusaurus 2.

## Implementation Notes :hammer_and_pick:

* Add initial Docusaurus website.
* Migrate existing docs to Docusaurus.
* Configure Prettier for Docusaurus.
* Add tutorials to OpenDC website (#28)
* Add deployment workflow via GitHub actions

## External Dependencies :four_leaf_clover:

* Docusaurus 2

Closes #28

5 files changed, 191 insertions, 0 deletions

diff --git a/site/docs/advanced-guides/_category_.json b/site/docs/advanced-guides/_category_.json
new file mode 100644
index 00000000..a74f4f42
--- /dev/null
+++ b/site/docs/advanced-guides/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Advanced Guides",
+  "position": 4,
+  "link": {
+    "type": "generated-index"
+  }
+}
diff --git a/site/docs/advanced-guides/architecture.md b/site/docs/advanced-guides/architecture.md
new file mode 100644
index 00000000..2a65a6c6
--- /dev/null
+++ b/site/docs/advanced-guides/architecture.md
@@ -0,0 +1,26 @@
+---
+sidebar_position: 2
+---
+
+# Architecture
+
+OpenDC consists of four components: a Kotlin simulator, a SQL database, a Quarkus-based
+[API](https://github.com/atlarge-research/opendc/tree/master/opendc-web/opendc-web-api), and a 
+React.js [frontend](https://github.com/atlarge-research/opendc/tree/master/opendc-web/opendc-web-api).
+
+![OpenDC Component Diagram](img/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/site/docs/advanced-guides/deploy.md b/site/docs/advanced-guides/deploy.md
new file mode 100644
index 00000000..2ee69c07
--- /dev/null
+++ b/site/docs/advanced-guides/deploy.md
@@ -0,0 +1,84 @@
+---
+sidebar_position: 3
+---
+
+# 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](https://github.com/atlarge-research/opendc/tree/master/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/site/docs/advanced-guides/img/component-diagram.png b/site/docs/advanced-guides/img/component-diagram.png
new file mode 100644
index 00000000..312ca72a
--- /dev/null
+++ b/site/docs/advanced-guides/img/component-diagram.png
diff --git a/site/docs/advanced-guides/toolchain.md b/site/docs/advanced-guides/toolchain.md
new file mode 100644
index 00000000..36efece7
--- /dev/null
+++ b/site/docs/advanced-guides/toolchain.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+---
+
+# 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)!
+
+## 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!