gege-jdr-backend/README.md

gege-jdr-backend

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.

Nix development shell

If you have direnv installed on your machine, run direnv allow . at the root of this project to automatically enter the Nix development shell for gege-jdr-backend.

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, in particular cargo. This project uses a precise version of Rust, check the rust-toolchain.toml file for more information;
• sqlx-cli, necessary for creating the database used by the backend and running its migrations;
• just, an alternative to Makefiles, for running commands more easily;
• cargo-audit, to verify whether the project contains known vulnerabilities;
• cargo-auditable, to audit the compiled binaries;
• cargo-tarpaulin, a code coverage tool for Rust;
• 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, to automatically run cargo commands on code changes;
• Docker to easily spin up a PostgreSQL database required by the backend, as well as Mailpit (see below)
• Mailpit to easily test sending emails without the need of a real SMTP server (included in the default dev Docker Compose file);
• rust-analyzer, the de facto standard LSP server for Rust;
• sqls, an SQL LSP server, useful when editing SQL files for migrations or tests.

Installing

Start by cloning the repository to your local machine:

$ git clone https://labs.phundrak.com/phundrak/gege-jdr-backend.git
$ cd gege-jdr-backend

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 and direnv 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 gege-jdr-backend will be using. You can do it manually, or you can spin up the Docker Compose file included with this repository.

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:

just docker-stop

Running the project

To run the project, you can run one of the two following commands:

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 gege-jdr-backend. 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:

just coverage

This command will run all the tests of the project and generate a code coverage report for gege-jdr-backend 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 for linting the project. You can run it with the following command:

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 to format its code. You can format your code with this command:

just format

You can also check if your code is properly formatted with:

just format-check

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use Semantic Versioning for versioning. For the versions available, see the tags on this repository.

Authors

• phundrak - Author and maintainer - phundrak

License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE (AGPL-3.0-or-later)

• see the 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;
• The CONTRIBUTING and CODE_OF_CONDUCT files are based on the files generated over at https://contributing.md/.