# ${REPO_NAME} ## Getting Started These instructions will give you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on deploying the project on a live system. ### Prerequisites You have two options for getting started: installing all the requirements locally, or using the included Nix development shell with [Nix flakes](https://nixos.wiki/wiki/flakes). #### Nix development shell If you have [`direnv`](https://direnv.net/) installed on your machine, run `direnv allow .` at the root of this project to automatically enter the Nix development shell for ${REPO_NAME}. Otherwise, you can simply run `nix develop` at the root of the project. All the necessary tools will be installed automatically, except for Docker (see below). #### Manually installing the prerequisites If you decide to install everything manually, you will need the following tools: - [Rust](https://www.rust-lang.org/), in particular `cargo`. This project uses a precise version of Rust, check the [rust-toolchain.toml](./rust-toolchain.toml) file for more information; - [sqlx-cli](https://github.com/launchbadge/sqlx/tree/main/sqlx-cli), necessary for creating the database used by the backend and running its migrations; - [just](https://just.systems/), an alternative to Makefiles, for running commands more easily; - [cargo-audit](https://github.com/rustsec/rustsec/tree/main/cargo-audit), to verify whether the project contains known vulnerabilities; - [cargo-auditable](https://github.com/rust-secure-code/cargo-auditable), to audit the compiled binaries; - [cargo-tarpaulin](https://github.com/xd009642/tarpaulin), a code coverage tool for Rust; - [cargo-msrv](https://crates.io/crates/cargo-msrv), to check whether your code respects the minimum supported Rust version used by this project. It is also recommended, though not necessary, to have the following tools installed: - [bacon](https://dystroy.org/bacon/), to automatically run cargo commands on code changes; - [Docker](https://www.docker.com/) to easily spin up a PostgreSQL database required by the backend, as well as Mailpit (see below) - [Mailpit](https://mailpit.axllent.org/) to easily test sending emails without the need of a real SMTP server (included in the default dev Docker Compose file); - [rust-analyzer](https://rust-analyzer.github.io/), the *de facto* standard LSP server for Rust; - [sqls](https://github.com/sqls-server/sqls), an SQL LSP server, useful when editing SQL files for migrations or tests. ### Installing Start by cloning the repository to your local machine: ```sh $ git clone ${REPO_HTTPS_URL} $ cd ${REPO_NAME} ``` Then, copy the `.env.example` file to a `.env` file and adjust it as you see fit. As mentioned above, if you have [Nix flakes](https://nixos.wiki/wiki/flakes) and [direnv](https://direnv.net/) installed, you can simply run `direnv allow .` to automatically set up your development environment. Otherwise, you should install every required tool yourself (including, if you want, the optional tools). You should then spin up a PostgreSQL database ${REPO_NAME} will be using. You can do it manually, or you can spin up the Docker Compose file included with this repository. ```sh just docker-start ``` This will launch a PostgreSQL 16 container based on the content of the `.env` file you created earlier. To stop the Docker containers, simply run the following command: ```sh just docker-stop ``` ## Running the project To run the project, you can run one of the two following commands: ```sh just run # starts the Docker containers automatically before # launching the project just run-no-docker # runs the project without the Docker containers ``` ## Running the tests There are two ways to run the tests of ${REPO_NAME}. The first one is the usual `cargo run`, which you can run with `just run`. It will simply run the tests and fail if one of them or more fails. There is a second option: ```sh just coverage ``` This command will run all the tests of the project and generate a code coverage report for ${REPO_NAME} in the `coverage/` directory. You will find both the `lcov` coverage file for the project, as well as an HTML file you can open in your browser to explore which line of code is covered or not. And, as with `just test`, if at least one of these tests fails, the code coverage will fail too and will display the same information. **NOTE**: The CI pipeline will run `just coverage` and will fail if any of the tests fails or if the code coverage drops below 60% of code covered by tests. ### Linting This project uses [clippy](https://github.com/rust-lang/rust-clippy) for linting the project. You can run it with the following command: ```sh just lint ``` **NOTE*: The CI pipeline will run `just lint` and will fail if the command fails too. It is strongly recommended to fix any issue from clippy before opening a pull request. ### Style test This project uses [rustfmt](https://github.com/rust-lang/rustfmt) to format its code. You can format your code with this command: ```sh just format ``` You can also check if your code is properly formatted with: ```sh just format-check ``` ## Contributing Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. ## Versioning We use [Semantic Versioning](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](${REPO_LINK}/tags). ## Authors - **${REPO_OWNER}** - *Author and maintainer* - [${REPO_OWNER}](https://labs.phundrak.com/${REPO_OWNER}) ## License This project is licensed under the [GNU AFFERO GENERAL PUBLIC LICENSE](LICENSE.md) (`AGPL-3.0-or-later`) - see the [LICENSE.md](LICENSE.md) file for details ## Acknowledgments - The `README` file is based on the templates you can find over at [github.com/PurpleBooth/a-good-readme-template](https://github.com/PurpleBooth/a-good-readme-template#readme); - The `CONTRIBUTING` and `CODE_OF_CONDUCT` files are based on the files generated over at .