gege-jdr-backend/README.md
Lucien Cartier-Tilet c73ff3d581
Some checks failed
CI / tests (push) Failing after 3m18s
Publish Docker image / publish (push) Failing after 13s
Initial commit
2024-08-10 12:02:33 +02:00

187 lines
6.2 KiB
Markdown

# 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](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 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](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 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](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 gege-jdr-backend 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 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:
```sh
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](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](/phundrak/gege-jdr-backend/tags).
## Authors
- **phundrak** - *Author and maintainer* -
[phundrak](https://labs.phundrak.com/phundrak)
<!-- See also the list of [contributors](/phundrak/gege-jdr-backend/contributors) who -->
<!-- participated in this project. -->
## 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 <https://contributing.md/>.