diff --git a/backend/README.md b/backend/README.md index 2739f4cd..8ece5aee 100644 --- a/backend/README.md +++ b/backend/README.md @@ -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://:@// + -e SMTP_SERVER= \ + -e SMTP_PORT= \ + -e SMTP_USERNAME= \ + -e SMTP_PASSWORD= \ + -e ADMIN_EMAIL= \ + -e FLICKR_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: @@ -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 `, where `` 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 🥘 @@ -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://:@:/ - -e SMTP_SERVER= \ - -e SMTP_PORT= \ - -e SMTP_USERNAME= \ - -e SMTP_PASSWORD= \ - -e ADMIN_EMAIL= \ - -e FLICKR_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:` where `` is of format `x.y` or `pre_x.y` for pre-releases. +2. To deploy to ghc login using `docker login ghcr.io -u --password-stdin` and provide access token with necessary permission. +3. Publish using `docker push ghcr.io/kronos-et-al/mensa-app:` + + + + +## 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 | @@ -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:` where `` is of format `x.y` or `pre_x.y` for pre-releases. -2. To deploy to ghc login using `docker login ghcr.io -u --password-stdin` and provide access token with necessary permission. -3. Publish using `docker push ghcr.io/kronos-et-al/mensa-app:` - - -## 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. \ No newline at end of file +to view these information, you can install the VSCode plugin "Coverage Gutters". It should work out of the box with the installed files. +