From 8f75336cb802b770d1ac53efb155632dd2dd94d2 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Thu, 8 Apr 2021 20:59:35 +0200 Subject: docs: Revamp project documentation This change updates the project documentation by moving most of the documentation to the docs directory. --- README.md | 116 +++++++++++++++++--------------------------------------------- 1 file changed, 31 insertions(+), 85 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3be20134..1d822e7e 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,50 @@ -

- OpenDC -
- OpenDC -

-

- Collaborative Datacenter Simulation and Exploration for Everybody -

+ + OpenDC logo + -
+# OpenDC -OpenDC is an open-source simulator for datacenters aimed at both research and education. +Collaborative Datacenter Simulation and Exploration for Everybody -![opendc-frontend-construction](misc/artwork/opendc-frontend-construction.png) +[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](/LICENSE.txt) +[![Documentation](https://img.shields.io/badge/docs-master-green.svg)](./docs) +[![GitHub release](https://img.shields.io/github/release/atlarge-research/opendc)](https://github.com/atlarge-research/opendc/releases) +[![Build](https://github.com/atlarge-research/opendc/actions/workflows/build-simulator.yml/badge.svg)](https://github.com/atlarge-research/opendc/actions/workflows/build-simulator.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-frontend-simulation](misc/artwork/opendc-frontend-simulation.png) +OpenDC is an open-source simulation platform for datacenters 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. +![Datacenter construction in OpenDC](docs/images/opendc-frontend-construction.png) -🛠 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). - -

- OpenDC Component Diagram -

- -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 +![Datacenter simulation in OpenDC](docs/images/opendc-frontend-simulation.png) -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. - -### 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. [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). -- cgit v1.2.3