124 lines
6.9 KiB
Markdown
124 lines
6.9 KiB
Markdown
Jobbörse
|
|
========
|
|
|
|
This project contains a web-server application to serve a listing of job offers including a form to submit new job offers with confirmation and review functionality.
|
|
|
|
Building the binary
|
|
-------------------
|
|
|
|
As the program is written in rust, a rust toolchain needs to be installed.
|
|
Instructions on how to install rustup, the standard toolchain manager for rust, can be found at <https://www.rust-lang.org/tools/install>.
|
|
|
|
The minimum required rust-toolchain version as of writing is `1.58` see the `rust-version` entry in the `Cargo.toml` file.
|
|
A stable toolchain is recommended.
|
|
It is recommended to use cargo for building as such make sure the `cargo` component of the toolchain is installed.
|
|
|
|
For a release build you can run `cargo build --release` this should build all dependencies and place the final binary in
|
|
the `./target/release/` folder.
|
|
|
|
For a development build you may run `cargo build --features=dev_mode`.
|
|
The dev-mode features allows enabling `development` mode which allows for live template reload.
|
|
With the feature specified a login provider which accepts all username password combinations is also added.
|
|
Enabling this feature will also place a banner at the top of the page informing of the fact that it's running from a dev-build.
|
|
|
|
Deployment
|
|
----------
|
|
|
|
The program expects to find the `static` and `templates` folder in the working directory.
|
|
By default, it starts in `production` mode, when build with the `dev-mode` feature `development` mode may also be specified using the `--mode` flag.
|
|
|
|
The table below list the default config path, it can be overridden using the `--config` flag.
|
|
|
|
| OS | Path |
|
|
| --------------------------------------- | ------------------------------------------------- |
|
|
| Linux | `/etc/jobboerse/config.toml` |
|
|
| Windows, if `${PROGRAMDATA}` is defined | `${PROGRAMDATA}/fs-infmath/jobboerse/config.toml` |
|
|
| Fallback | `./config.toml` |
|
|
|
|
See `ProgramArguments::default_config` in `src/server_config.rs` for reference.
|
|
|
|
Should the config path not exist, then a default config will be used and written to disk.
|
|
|
|
The port 8080 will be used by default, this can be changed with the `--port` flag.
|
|
|
|
The default log level is `INFO`, logging can be configured via the `RUST_LOG` environment variable as described
|
|
in the [`env_logger` documentation](https://docs.rs/env_logger/0.7.1/env_logger/index.html).
|
|
Note: Currently the documentation for version 0.7.1 is relevant, even if it not the newest version.
|
|
An update of `pretty_env_logger` should hopefully be available soon to change this.
|
|
See [PR 49](https://github.com/seanmonstar/pretty-env-logger/pull/49) in the pretty_env_logger repo, which updates the env_logger dependency.
|
|
|
|
Config
|
|
------
|
|
|
|
The config file uses the toml format.
|
|
The expected fields are defined by the `ProgramConfig` struct in `./src/server_config.rs`.
|
|
|
|
| config field | required | default |
|
|
| ------------------- | -------- | -------------- |
|
|
| `url_base_path` | false | empty |
|
|
| `data_storage_path` | false | `./job_offers` |
|
|
| `banner` | false | no banner |
|
|
| `login_provider` | true | N/A |
|
|
| `email` | false | no email |
|
|
| `webhook_url` | false | no webhook |
|
|
|
|
Note: when email is not configured, no confirmation e-mails will be sent, but confirmation is still required!
|
|
|
|
For `login_provider` there are four types available: `Ldap`, `Simple`, `Disabled`, and `Development`.
|
|
The last of which is only available when build with the `dev-mode` feature.
|
|
Selecting a specific type is done by setting the `type` field to the name of the login provider, this is case-sensitive.
|
|
|
|
`Disabled` and `Development` have no further options.
|
|
|
|
The `Simple` login provider requires the `file_path` to be set, which points to a toml file containing
|
|
a `users` table.
|
|
The table keys are then used as usernames and the associated values are expected to be strings containing plaintext passwords.
|
|
|
|
The `Ldap` login provider takes the following configuration fields.
|
|
The `server_address` field specifies a URL under which the ldap server is reached.
|
|
The `starttls` options defines whether StartTLS should be used (default is true, though ignored if incompatible with URL).
|
|
The `ldap_user_dn` contains a pattern for the user dn for simple bind as well as search `%{username}` is replaced by the ldap-dn-escaped username.
|
|
The `dap_user_filter` specifies a filter pattern for an ldap search, `%{username}` is replaced by the ldap-escaped username.
|
|
|
|
`THIRDPARTY.toml`
|
|
-----------------
|
|
|
|
This file is generated using the `cargo-bundle-licenses` tool and contains license information for all third-party dependencies.
|
|
It is manually adjusted to include all not auto-detected licenses.
|
|
When re-generating this file make sure to not lose still relevant manually inserted licenses and to add newly missing licenses.
|
|
|
|
Alternatively, the `THIRDPARTY.toml` may be regenerated as described below.
|
|
Regenerating this file usually requires some manual intervention, to fix licenses that were not automatically detected.
|
|
|
|
To regenerate this file the cargo-bundle-licenses tool needs to be available.
|
|
It can be installed via `cargo install cargo-bundle-licenses`.
|
|
At least version 1.0.0, is required, for normalization of license file path located under `$CARGO_HOME`.
|
|
It can then be run with `cargo bundle-licenses --format toml --output THIRDPARTY.toml` to re-generate the file.
|
|
The script `./scripts/generate_thirdparty.sh` does just that.
|
|
This needs to be done when dependencies change to adjust the corresponding entries.
|
|
Make sure to look for entries for which the license text is listed as `NOT FOUND` and insert the appropriate license.
|
|
|
|
Testing
|
|
-------
|
|
|
|
General Tests: `cargo test`
|
|
|
|
Check Formatting: `cargo fmt --check`
|
|
|
|
cargo-deny (installed separately): `cargo deny check`
|
|
|
|
cargo-msrc (installed separately): `cargo msrv --verify`
|
|
|
|
Cutting a Release
|
|
-----------------
|
|
|
|
* Update the version in the root Cargo.toml according to semver, this will be the version to-be-cut
|
|
* Update the changelog to reflect all changes since the last release under `[Unreleased]`
|
|
* It's generally recommended to keep the Changelog up to date by adding changes to the unreleased section in the commit that introduces the change
|
|
* In the now up-to-date changelog add a new section heading for the version to-be-cut between `[Unreleased]` and the first entry of the unreleased section
|
|
* Add a matching link definition at the bottom of a changelog
|
|
* Update the version in dist/arch/PKGBUILD to match the version to-be-cut
|
|
* run cargo test to update the version in the Cargo.lock file and check that the tests pass
|
|
* Commit & Push your changes and wait for them to be merged
|
|
* Tag the merge(d) commit as the release and push the tag
|
|
* You have Cut a new Release, Congratulations
|