Commit acb4d10e authored by Robert Czechowski's avatar Robert Czechowski
Browse files

Update README.md: Translation, folder structure, deployment. Closes #48.

parent a7ae9cd4
Pipeline #806 passed with stages
in 20 minutes and 57 seconds
......@@ -4,22 +4,48 @@ Medal is a small platform for in-browser running contest written in rust.
It is designed for the German "Jugendwettbewerb Informatik", a computer science contest with tasks using Google Blockly as a programming language-replacement.
Try it out on https://jwinf.de/!
## Translation
Currently there is no translation framework built into medal, but it is high on our todo list.
If you want to translate the platform or parts of it into another language, don't hesitate to let us know by opening a ticket or writing an email to jugendwettbewerb [a.t] bwinf.de.
## Folder structure (administration)
### `tasks/`
Contains all the tasks files and the contests.
Tasks are HTML files that are served directly and can reference other files (CSS, JS, images).
Contest are YAML files following a certain structure (see src/contestreader_yaml.rs). Upon start of the platform, the whole tasks directory and all subdirectories are scanned for .yaml files and every .yaml file is parsed as contest and inserted into the database or updated (if the filename stays the same).
#### `tasks/jwinf/` (using FIOI tasks)
In order to use the france-ioi-style tasks that are used on https://jwinf.de/, the wrappers files in `tasks/jwinf/` have to be used in contest definitions to wrap the tasks and allow for communication between task an plattform.
Also the repository https://github.com/France-ioi/bebras-modules.git has to be checked out, since the tasks depend on it. Usually it should be checked out at `tasks/jwinf/_common/modules`.
## Folder structure
#### `tasks/teacher/`
### tasks/
The directory `tasks/teacher/` can contain an `index.html` file. This file is presented to teachers in the teacher area of the platfrom (in an iframe). Further sites or documents can be linked from it.
### `templates/`
The folder `templates/` contains the different template sets. The template set can be selected in `config.json` or via command line parameter. By default, the template set `default/` is chosen.
### `config.json`
The `config.json` configures the plattform (see src/config.rs).
## Running Medal
Needs `rustc` and `cargo` 1.34 (stable) or higher[^1].
Needs `rustc` and `cargo` 1.40 (stable) or higher.
Rust can be obtained here: https://rustup.rs/
......@@ -39,7 +65,34 @@ The directories `tasks/` and `static/` can (and for throughput-purposes should)
## Deploy
It is recommended to run the platform behind a reverse proxy, that is serving static files directly.
It is recommended to run the platform behind a reverse proxy, that is serving static files directly. However, the contest YAML files should not be served to the user!
The following configuration can be used for an Nginx webserver:
```
upstream medal {
server [::1]:8000;
}
server {
# Other server settings here
location ~* \.(yaml)$ {
deny all;
}
location /static {
add_header Cache-Control "public, max-age=604800";
}
location /tasks {
add_header Cache-Control "public, max-age=604800";
}
location / {
proxy_pass http://medal;
}
```
The following configuration can be used for an Apache 2.4 webserver:
......@@ -58,20 +111,25 @@ The following configuration can be used for an Apache 2.4 webserver:
Alias "/static/" "/path/to/medal/static/"
Alias "/favicon.ico" "/path/to/medal/static/images/favicon.png"
<filesMatch ".(css|jpg|jpeg|png|gif|js|ico)$">
<filesMatch "\.(css|jpe?g|png|gif|js|ico)$">
Header set Cache-Control "max-age=604800, public"
</filesMatch>
<FilesMatch "\.yaml$">
Deny from all
</FilesMatch>
<Directory "/path/to/medal/static/">
Require all granted
</Directory>
<Directory "/path/to/medal/tasks/">
Require all granted
</Directory>
```
## Contributing
Please format your code with `rustfmt` and check it for warnings with `clippy`.
......@@ -88,8 +146,38 @@ make format
make clippy
```
## Folder structure (development)
### `migrations/`
Contains all the database migrations. New database migrations are applied when the platform is started. This can be disabled in the config or via command line switch.
### `src/`
#### `src/main.rs`
Entry point of the program and contains all integration tests.
#### `src/core.rs`
The core logic of all http endpoint.
#### `src/webfw_iron.rs`
Connects the core logic to the webframework (in this case `iron`).
#### `src/db_conn.rs`, `src/db_objects.rs`
Provides a database abstraction for the core logic.
#### `src/db_conn_*.rs`
Implement the database abstraction for different database types.
The files `src/db_conn_*.rs` are generated by `generate_connectors.sh` from `src/db_conn.base.rs` and `src/db_conn_*.header.rs`.
## Footnotes
#### Other
[^1]: Can be compiled with rust 1.32 or higher without much work by downgrading the version of the `reqwest` crate. However, the test cases will not compile, then, due to usage of the cookie jar features of reqwest.
\ No newline at end of file
* `helpers.rs` small helper functions
* `config.rs` parse config file
* `contestreader_yaml.rs` parse contest files
* `db_apply_migrations.rs` read `migrations/` directory and apply found files to migration functions of db connectors
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment