Mirrors
/
VILLASweb
mirror of https://git.rwth-aachen.de/acs/public/villas/web/
1
0
Fork 0
Code Issues Releases Wiki Activity

move and consolidate documentation with main VILLAS documentation repo

This commit is contained in:
Steffen Vogel 2021-01-26 16:37:22 +01:00
parent 98e9e86757
commit ab679f4b11
5 changed files with 4 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@ -2,39 +2,15 @@
[![pipeline status](https://git.rwth-aachen.de/acs/public/villas/web/badges/master/pipeline.svg)](https://git.rwth-aachen.de/acs/public/villas/web/-/commits/master)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
This is VILLASweb, the website to configure real-time co-simulations and display simulation real-time data in the web browser.
The term **frontend** refers to this project, the actual website.
The frontend connects to **two** backends: [VILLASweb-backend-go](https://git.rwth-aachen.de/acs/public/villas/web-backend-go) and [VILLASnode](https://git.rwth-aachen.de/acs/public/villas/node).
VILLASnode provides actual simulation data via websockets. VILLASweb-backend-go provides any other data such as user accounts, infrastructure components and configurations, dashboards etc.
For more information on the backends see their repositories.
VILLASweb is a tool to configure real-time co-simulations and display simulation real-time data in the web browser.
## Frameworks
The frontend is build upon [ReactJS](https://facebook.github.io/react/) and [Flux](https://facebook.github.io/flux/).
React is responsible for rendering the UI and Flux for handling the data and communication with the backends. For more information also have a look at REACT.md
Additional libraries are used, for a complete list see the file `package.json`.
## Data model
![Datamodel](src/img/datamodel.png)
## Quick start
```bash
$ git clone --recursive https://git.rwth-aachen.de/acs/public/villas/web.git
$ cd web
$ npm install
$ npm start
```
We recommend to start the VILLASweb-backend-go before the frontend.
If you want to use test data (including some test users), you can start the backend with the parameter `-mode=test`.
Please check the repository of the VILLASweb-backend-go to find information on the test user login names and passwords.
The testing mode is NOT intended for production deployments.
## Documentation
More details on the setup and usage of VILLASweb is available here:
- [Requirements](doc/Requirements.md)
- [Structure and datamodel](doc/Structure.md)
- [Development setup](doc/development.md)
- [Production setup](doc/Production.md)
More details on the setup and usage of VILLASweb is available [in the VILLAS documentation](https://villas.fein-aachen.org/doc/web.html).
## Copyright
@ -70,7 +46,7 @@ For other licensing options please consult [Prof. Antonello Monti](mailto:amonti
[![EONERC ACS Logo](doc/pictures/eonerc_logo.png)](http://www.acs.eonerc.rwth-aachen.de)
- Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
- Steffen Vogel <svogel2@eonerc.rwth-aachen.de>
- Sonja Happ <sonja.happ@eonerc.rwth-aachen.de>
[Institute for Automation of Complex Power Systems (ACS)](http://www.acs.eonerc.rwth-aachen.de)

82
doc/Production.md
View File

@ -1,82 +0,0 @@
# Production Setup {#web-production}
## Setting up VILLASweb for production
For development setup instructions see @ref web-development.
The production setup is based on docker.
Clone the [frontend](https://git.rwth-aachen.de/acs/public/villas/web) and [backend](https://git.rwth-aachen.de/acs/public/villas/web-backend-go) repositories on your computer and build the Docker images for both:
### Frontend
- `cd VILLASweb`
- `docker build -t villasweb-frontend .`
### Backend
- `cd ..\VILLASweb-backend-go`
- `docker build -t villasweb-backend .`
### WIP Docker compose and/or Kubernetes
Run the production docker-compose file:
- `docker-compose -f docker-compose-production.yml up -d`
## Configure VILLASnode to get data into VILLASweb
### Install VILLASnode
See: @ref node-installation
### Create a VILLASnode demo data source
1. Create a new empty configuration file with the following contents and save it as `webdemo.conf`:
> WIP this example configuration requires revision!
```
nodes = {
sine = {
type = "signal"
signal = "mixed"
values = 5
rate = 25
frequency = 5
}
web = {
type = "websocket"
destinations = [
"TODO"
]
}
}
paths = (
{
in = "sine"
out = "web"
}
)
```
The node `sine` is a software signal generator for 5 signals.
The node `web` is the websocket interface to stream the data generated by the `sine` node to the browser.
> Note: If you do not want to use your local system as the destination for the websocket node,
>change the option `destinations` of the `web` node to the destination of your production environment, for example `https://my.production.environment/ws/webdemo`.
### Start the VILLASnode gateway
Run the following command on your system:
```bash
villas node webdemo.conf
```
> Note: Change the path to the configuration file accordingly. The `villas` command will only work if VILLASnode is installed on your system.
### Visualize real-time data in VILLASweb Dashboards
1. Use the VILLASweb frontend to create a new infrastructure component for the VILLASnode gateway from above (Admin user required).
2. Set the `websocketurl` parameter of the component to the target you used as the `web.destinations` parameter in the configuration from above.
3. Create a new scenario in VILLASweb and within that scenario create a new component configuration that uses the infrastructure component you created under 2.
4. WIP: Use the signal auto-configure function to retrieve the signal configuration of the VILLASnode automatically.
5. Create a new dashboard with widgets of your choice and link these widgets to the signals received from the infrastructure component.
6. Enjoy what you see.

12
doc/Requirements.md
View File

@ -1,12 +0,0 @@
# Requirements {#web-requirements}
## Services and tools required for development
- [NodeJS with npm](https://nodejs.org/en/): Runs VILLASweb frontend
- [Go](https://golang.org/): Runs VILLASweb backend
- [PostgreSQL database](https://www.postgresql.org/) (min version 11): Backend database
- [swag](https://github.com/swaggo/swag): For automated API documentation creation
- [Docker](https://www.docker.com/): Container management system
## Additional requirements for productive use
- [NGinX](https://www.nginx.com/): Webserver and reverse proxy for backends

79
doc/Structure.md
View File

@ -1,79 +0,0 @@
# VILLASweb data structure {#web-datastructure}
This document describes how data (scenarios, infrastructure components, users etc., not only live data) is structured in VILLASweb.
## Data model
![Datamodel](../src/img/datamodel.png)
VILLASweb features the following data classes:
- Users
- Infrastructure Components
- Scenarios
* Component Configurations and Signals
* Dashboards and Widgets
* Files
### Users
- You need a username and a password to authenticate in VILLASweb
- There exist three categories of users: Guest, User, and Admin
- Guests have only read access and cannot modify anything
- Users are normal users, they have access to their scenarios, can see available infrastructure components, and modify their accounts (except for their role)
- Admin users have full access to everything, they are the only users that can create new users or change the role of existing users. Only admin users can add or modify infrastructure components.
### Infrastructure Components
- Components of research infrastructure
- Category: for example simulator, gateway, amplifier, database, etc.
- Type: for example RTDS, OpalRT, VILLASnode, Cassandra
- Can only be added/ modified by admin users
### Scenarios
- A collection of component configurations, dashboards, and files for a specific experiment
- Users can have access to multiple scenarios
- Users can be added to and removed from scenarios
### Component Configurations and Signals
- Configure an infrastructure component for the use in a specific scenario
- Input signals: Signals that can be modified in VILLASweb
- Output signals: Signals that can be visualized on dashboards of VILLASweb
- Parameters: Additional configuration parameters of the infrastructure component
- Signals are the actual live data that is displayed or modified through VILLASweb dashboards
### Dashboards and Widgets
- Visualize ongoing experiments in real-time
- Interact with ongoing experiments in real-time
- Use widgets to design the dashboard according to the needs
### Files
- Files can be added to scenarios optionally
- Can be images, model files, CIM xml files
- Can be used in widgets or component configurations
## Setup strategy
The easiest way to start from scratch is the following (assuming the infrastructure components are already configured by an admin user, see below):
1. Create a new scenario.
2. Create and configure a new component configuration and link it with an available infrastructure component.
3. Configure the input and output signals of the component configuration according to the signals provided by the selected infrastructure component. The number of signals and their order (index starting at 1) must match.
4. Create a new dashboard and add widgets as desired. Configure the widgets by right-clicking to open the edit menu
5. If needed, files can be added to the scenario and used by component configurations or widgets (models, images, CIM-files, etc.)
6. For collaboration with other users, users can be added to a scenario
### Setup of infrastructure components
In the "Infrastructure Components" menu point admin users can create and edit components to be used in experiments. Normal uses can view the available components, but not edit them.
The components are global at any time and are shared among all users of VILLASweb.
To create a new infrastructure component, you need to provide:
- Name
- Category (see above for examples)
- Type (see above for examples)
- Location
- Host (network address of the component)
At the moment, you need to know the input and output signals of the infrastructure component a priori to be able to create compatible component configurations by hand.
An auto-detection mechanism for signals is planned for future releases.
> Hint: At least one infrastructure component is required to receive data in VILLASweb.

70
doc/development.md
View File

@ -1,70 +0,0 @@
# Development {#web-development}
- @subpage web-datastructure
In order to get started with VILLASweb, you might also want to check our our [demo project](https://git.rwth-aachen.de/acs/public/villas/Demo) which is simple to setup using Docker Compose.
## Frontend
### Description
The website itself based on the [React JavaScript framework](https://reactjs.org/) and the [Flux library](https://facebook.github.io/flux/).
### Required
- [NodeJS with npm](https://nodejs.org/en/)
### Setup
- `git clone git@git.rwth-aachen.de/acs/public/villas/web.git` to copy the project on your computer
- `cd VILLASweb`
- `npm install`
### Running
- `npm start`
This runs the development server for the website on your local computer at port 3000.
The backend must be running to make the website work.
Type `http://localhost:3000/` in the address field of your browser to open the website.
## Backend
### Description
The backend of VILLASweb uses the programming language Go and a PostgreSQL database.
### Required
- [Go](https://golang.org/) (min version 1.11)
- [PostgreSQL database](https://www.postgresql.org/) (min version 11)
- [swag](https://github.com/swaggo/swag)
### Setup and Running
- `git clone git@git.rwth-aachen.de/acs/public/villas/web-backend-go.git` to copy the project on your computer
- `cd VILLASweb-backend-go`
- `go mod tidy`
- `go run start.go [params]`
To obtain a list of available parameters use `go run start.go --help`.
To run the tests use `go test $(go list ./... ) -p 1` in the top-level folder of the repo.
Running the backend will only work if the PostgreSQL database is setup properly. Otherwise, you will get error messages.
### Auto-generate the API documentation
The documentation of the VILLASweb API in the OpenAPI format can be auto-generated from the source code documentation using the tool swag.
To do this run the following in the top-level folder of the repo:
- `go mod tidy`
- `go install github.com/swaggo/swag/cmd/swag`
- `swag init -p pascalcase -g "start.go" -o "./doc/api/"`
The `.yaml` and `.json` files in OpenAPI swagger format are created in the output folder `doc/api`.
### PostgreSQL database setup
Please check the [Readme file in the backend repository](https://git.rwth-aachen.de/acs/public/villas/web-backend-go) for some useful hints on the local setup of the PostreSQL database.