ap7pd/event-management-backend
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Update readme

Browse source
This commit is contained in:
Peter Vacho 2024-12-30 02:57:22 +01:00
parent 9d8fa611b1
commit 8bbc3fe4bb
Signed by: school
GPG key ID: 8CFC3837052871B4
1 changed files with 48 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
README.md
View file

@ -90,8 +90,10 @@ poe run-dev
## Docker
As an alternative process to manually installing & running the project, you can also use the docker-compose file, which
will pull all the necessary dependencies and start the backend, as well as the MongoDB instance.
As an alternative process to manually installing & running the project, you can also docker, which should allow running
the project anywhere, without installing all of the dependencies manually. This is a lot more convenient way to run
projects, especially if you're not interested in doing any further development on it. Especially since the docker
compose file provided includes a MongoDB instance as well, so you won't need to set that up yourself.
First, you will need to have [Docker](https://docs.docker.com/engine/install/) and [Docker
compose](https://docs.docker.com/compose/install/) installed. Once you have that, you can run:
@ -101,15 +103,16 @@ sudo docker-compose up
```
This will build the docker image from the attached `Dockerfile` and pull another image for the MongoDB instance. Once
done, it will start the backend server and the MongoDB instance. By default, the backend will be available at port 8000
with host 0.0.0.0. Feel free to edit the `docker-compose.yml` file and change it.
done, it will start the backend server and the MongoDB instance. By default, the backend will be available at port 8000.
Feel free to edit the `docker-compose.yml` file and change it.
Note that if you change the code, it is necessary to also rebuild the docker image. You can do that by adding the
`--build` flag to the command:
```bash
sudo docker up --build
```
> [!NOTE]
> Note that if you change the code, it is necessary to also rebuild the docker image. You can do that by adding the
> `--build` flag to the command:
>
> ```bash
> sudo docker up --build
> ```
If you wish to run the containers in the background, you can add the `-d` flag:
@ -123,6 +126,13 @@ sudo docker-compose up -d
> set from there. That said, there are still some other required values that you will need to set. You can read more
> about how to configure the project in the [Configuration](#configuration) section.
> [!NOTE]
> By default, the docker container will always use a brand new database. If you wish to persist the database across
> runs, you will need to modify the docker-compose file and add a [docker
> volume](https://docs.docker.com/engine/storage/volumes/#use-a-volume-with-docker-compose) or a directory [bind
> mount](https://docs.docker.com/engine/storage/bind-mounts/#use-a-bind-mount-with-compose). By default, MongoDB will
> store the data in `/data/db` directory.
## Configuration
To configure the project, you can either set the environment variables manually or create a `.env` file in the root directory of
@ -130,20 +140,22 @@ the project(the same folder that this README file is in).
Currently, you will need to set 2 environment variables:
- `JWT_SECRET_TOKEN`: This is the secret token that will be used to sign the JWT tokens. This should be a long, random
string. I'd recommend generating it with `openssl rand -hex 32` command (if you're on windows, you can use `openssl`
from WSL or generate it through some other means, or use the one in the example later though, although I wouldn't
recommend that for production use).
- `MONGODB_URI`: This is the connection string for the MongoDB instance. This should be in the format
- **`JWT_SECRET_TOKEN`:** This is the secret token that will be used to sign the JWT tokens. This should be a long,
random string. I'd recommend generating it with `openssl rand -hex 32` command (if you're on windows, you can use
`openssl` from WSL or generate it through some other means, or use the one in the example later though, although I
wouldn't recommend that for production use).
- **`MONGODB_URI`:** This is the connection string for the MongoDB instance. This should be in the format
`mongodb://username:password@host:port/database`. If you're using the admin authsource, you can also add
`?authSource=admin` suffix to this string. Note that if you're using the docker-compose, you don't need to set this
value, as it's already set in the `docker-compose.yml` file.
There are also some optional environment variables that you can set:
- `DEBUG`: This is a boolean value that will enable the debug mode in the FastAPI application. This is useful for
- **`DEBUG`:** This is a boolean value that will enable the debug mode in the FastAPI application. This is useful for
development, but you should never enable this in production. If you don't set this value, it will default to `0`
(false). To enable it, set this to `1` (true).
- **`LOG_FILE`:** If set, also write the logs into given file, otherwise only write to stdout (printing the logs).
- **`TRACE_LEVEL_FILTER`:** Configuration for trace level logging, see: [trace logs config section](#trace-logs-config)
### Example `.env` file
@ -154,3 +166,22 @@ DEBUG=0
JWT_SECRET_TOKEN=e51ca69e8d42422c7d2f94bc14e9aaaf294bb55a881354633f5e44f2dc9fde71
MONGODB_URI=mongodb://root:test@localhost:27017/my-cool-database?authSource=admin
```
### Trace logs config
We have a custom `trace` log level for the project, which can be used for debugging purposes. This level is below
`debug` and can only be enabled if `DEBUG=1`. This log level is controlled through the `TRACE_LEVEL_FILTER` environment
variable. It works in the following way:
> [!NOTE]
> Due to the time constrains imposed on the project, the logging is sometimes somewhat lacking and there actually aren't
> that many trace level logs. This is something that could be improved in the future, if further development is done.
- If `DEBUG=0`, the `TRACE_LEVEL_FILTER` variable is ignored, regardless of it's value.
- If `TRACE_LEVEL_FILTER` is not set, no trace logs will appear (debug logs only).
- If `TRACE_LEVEL_FILTER` is set to `*`, the root logger will be set to `TRACE` level. All trace logs will appear.
- When `TRACE_LEVEL_FILTER` is set to a list of logger names, delimited by a comma, each of the specified loggers will
be set to `TRACE` level, leaving the rest at `DEBUG` level. For example:
`TRACE_LEVEL_FILTER="src.api.foo.foobar,src.api.bar.barfoo"`
- When `TRACE_LEVEL_FILTER` starts with a `!` symbol, followed by a list of loggers, the root logger will be set to
`TRACE` level, with the specified loggers being set to `DEBUG` level.