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.

It may be necessary to run ./scripts/adjust_thirdparty.sh to adjust some absolute paths in the THIRDPARTY.toml, though this should only be required to run tests.

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. 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 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

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 unter [Unreleased]
  • It's generally recommended to keep the Changelog upto 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