rust-poem-openapi-template/README.md

# ${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})

<!-- See also the list of [contributors](${REPO_LINK}/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/>.