Skip to content

Commit

Permalink
lots of reordering
Browse files Browse the repository at this point in the history
  • Loading branch information
@worldofjoni
worldofjoni committed Aug 21, 2023
1 parent d362f64 commit 7ef7ac0
Showing 1 changed file with 84 additions and 59 deletions.
143 changes: 84 additions & 59 deletions backend/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,37 @@ Backend application for providing and synchronizing meal plan data of the cantee

[^1]: https://www.sw-ka.de/de/hochschulgastronomie/speiseplan/

## Environment variables

## Running the backend yourself

### Deploy using docker-compose
The easiest way to run the backend is by using [docker compose](https://docs.docker.com/compose/).
1. Install docker
2. Download the [compose.yaml](compose.yaml?raw=true) file
3. Modify the environment variables and other configurations inside the file accordingly
1. For the first start you may want to uncomment the `command: --migrate` line to crate the database schema automatically
4. run `docker compose up -d` next to the file

### Deploy using Docker
If you only want to run the backend and want to provide a database by other means, you can run the backend container using:
(Is you use docker compose, this is not necessary!)
```
docker run -d --name mens-app-backend \
-p 80:80
-e DATABASE_URL=postgres://<db user>:<db password>@<db host>/<db port>/<db name>
-e SMTP_SERVER=<domain of mail server> \
-e SMTP_PORT=<port of mail server> \
-e SMTP_USERNAME=<username of mail server> \
-e SMTP_PASSWORD=<password of mail server> \
-e ADMIN_EMAIL=<email address admin notofocations should be send to> \
-e FLICKR_API_KEY=<flickr public api key> \
ghcr.io/kronos-et-al/mensa-app
```

Running the container requires a postgres database, connection to a mail server and a flickr api key.


### Environment variables
To pass configuration options to the backend application environment variables are used.
Alternatively, a `.env` file can be provided in the current execution directory.
The following options are available:
Expand All @@ -25,7 +55,39 @@ The following options are available:
| `CANTEENS` | Comma (`,`) separated list of canteens which should be requested and parsed. These are appended on the `MENSA_BASE_URL`. | `mensa_adenauerring,mensa_gottesaue,mensa_moltke,mensa_x1moltkestrasse,mensa_erzberger,mensa_tiefenbronner,mensa_holzgarten` |
| `USER_AGENT` | [User agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) used for requesting meal plan data. Fore some reason, this can not be empty. | `MensaKa <version>`, where `<version>` is the current version of the application (as specified in the rust crate) |
| `HTTP_PORT` | Port to listen on for API requests | `80` |
## Command line arguments



## Building the backend

### First Setup
To compile the backend, you need cargo, you can install it here: https://www.rust-lang.org/tools/install.

For writing rust code, VSCode with the `rust-analyzer` extension is recommended.
It is also recommended to set the `rust-analyzer.check.command` setting to `clippy`

#### Environment Variables
For deployment of the server, initial settings like API tokens and other access information are passed as environment variables.
To make development easier, these can also be defined textually in a `.env` file. A preset with all available options is provided as `.env.default`. The `.env` file is the **only place you can put credentials safely** so that they get not published in the _public_ git repository.

#### Database
If you work on database parts, you need to setup a local dev database first:
1. Setup your environment variable for the database in the `.env` file. The default should be ok when you use the command below for your database.

2. Install docker and run to spun up a database:
```bash
docker run -itd -e POSTGRES_USER=postgres_user -e POSTGRES_PASSWORD=secret_password -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_DB=mensa_app -p 5432:5432 -v data:/var/lib/postgresql/data --name postgresql postgres
```
This runs a postgres database as a docker container.
To setup all relations install `cargo install sqlx-cli` and run `cargo sqlx mig run`.

3. If you want to reset the database (because you changed the migrations) run `sqlx database reset`


### Run the backend
- Run `cargo run --bin mensa-app-backend` to build and run the backend.

#### Command line arguments
```
==================================================
MensaApp Backend v0.1 🥘
Expand All @@ -48,35 +110,29 @@ migrate --migrate

```
## Deploy using Docker
The docker container can be run using
```
docker run \
-p 80:80
-e DATABASE_URL=postgres://<db user>:<db password>@<db host>:<db port>/<db name>
-e SMTP_SERVER=<domain of mail server> \
-e SMTP_PORT=<port of mail server> \
-e SMTP_USERNAME=<username of mail server> \
-e SMTP_PASSWORD=<password of mail server> \
-e ADMIN_EMAIL=<email address admin notofocations should be send to> \
-e FLICKR_API_KEY=<flickr public api key> \
ghcr.io/kronos-et-al/mensa-app
```

Running the container requires a postgres database, connection to a mail server and a flickr api key.

## Building
- Run `cargo fmt` to format all code files.
- Run `cargo clippy` to check for errors and recommendations.
- Run `cargo run` to build and run the backend.

### Graphql mock server
To run a mock version of the graphql server, run `cargo run --bin graphql_mock`.
### Documentation
The documentation can be accessed with `cargo doc --open`.
## Logging
### Build Docker
1. To build the docker container, run `docker build . -t ghcr.io/kronos-et-al/mensa-app:<verion>` where `<version>` is of format `x.y` or `pre_x.y` for pre-releases.
2. To deploy to ghc login using `docker login ghcr.io -u <username> --password-stdin` and provide access token with necessary permission.
3. Publish using `docker push ghcr.io/kronos-et-al/mensa-app:<version>`
## Contribution
Before submitting changes to the code, you should run
- `cargo fmt` to format all code files.
- `cargo clippy` to check for errors and recommendations.
- `cargo sqlx prepare` if you have changed database queries or migrations. This is to prepare information on these queries so that others can still compile the backend without having a local dev database. See also [sqlx-cli/README.md](https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md#enable-building-in-offline-mode-with-query).
- `cargo test` to make sure all test are ok
### Logging
Whenever an action of importance happens or a silent error occurs (which does not get transported to the next upper layer) a logging message shall get produced.
The following log levels are available:
| level | syntax | usecase |
Expand All @@ -87,40 +143,9 @@ The following log levels are available:
| WARN | `warn!(...);` | An error occurred but execution can continue. This includes situations like when a meal could not be resolved and added to the meal plan, but other meals are and will be added fine. |
| ERROR | `error!(...);` | A fatal error which does _may not_ lead to program termination but marks a serious malcondition. This includes failed sending of an email. |
## First Setup
To compile the backend, you need cargo, you can install it here: https://www.rust-lang.org/tools/install.
For writing rust code, VSCode with the `rust-analyzer` extension is recommended.
It is also recommended to set the `rust-analyzer.check.command` setting to `clippy`
### Testing Coverage
### Environment Variables
For deployment of the server, initial settings like API tokens and other access information are passed as environment variables.
To make development easier, these can also be defined textually in a `.env` file. A preset with all available options is provided as `.env.default`. The `.env` file is the **only place you can put credentials safely** so that they get not published in the _public_ git repository.

### Databse
1. Setup your environment variable for the database. The default should be ok when you use the command below for your database.

2. Install docker and run to spun up a database:
```bash
docker run -itd -e POSTGRES_USER=postgres_user -e POSTGRES_PASSWORD=secret_password -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_DB=mensa_app -p 5432:5432 -v data:/var/lib/postgresql/data --name postgresql postgres
```
This runs a postgres database as a docker container.
To setup all relations install `cargo install sqlx-cli` and run `cargo sqlx mig run`.


1. After adding a query in rust code, make sure to run `cargo sqlx prepare` to safe the database format for offline usage so compilation can be successful even if no database is present.

2. After adding a query in rust code, make sure to run `cargo sqlx prepare` to safe the database format for offline usage so compilation can be successful even if no database is present.

3. If you want to reset the database (because you changed the migrations) run `sqlx database reset`


### Docker
1. To build the docker container, run `docker build . -t ghcr.io/kronos-et-al/mensa-app:<verion>` where `<version>` is of format `x.y` or `pre_x.y` for pre-releases.
2. To deploy to ghc login using `docker login ghcr.io -u <username> --password-stdin` and provide access token with necessary permission.
3. Publish using `docker push ghcr.io/kronos-et-al/mensa-app:<version>`


## Testing
To show test coverage, you need to install `cargo install cargo-tarpaulin`. Then you can run `cargo tarpaulin --out Lcov` to generate coverage info.
to view these information, you can install the VSCode plugin "Coverage Gutters". It should work out of the box with the installed files.
to view these information, you can install the VSCode plugin "Coverage Gutters". It should work out of the box with the installed files.

0 comments on commit 7ef7ac0

Please sign in to comment.