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

Fully explain how to install/run the project

Browse source
This commit is contained in:
Peter Vacho 2024-12-29 17:08:26 +01:00
parent d7cac9813b
commit fb7f49c04e
Signed by: school
GPG key ID: 8CFC3837052871B4
1 changed files with 143 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
README.md
View file

@ -2,14 +2,155 @@
This project was created as a part of the final assignment for AP7PD, alongside the frontend that is tracked in a separate repository. This project was created as a part of the final assignment for AP7PD, alongside the frontend that is tracked in a separate repository.
This project is also a dependency for the frontend project, which is re-used as the final project for AP7MP as well.
## Description ## Description
This backend facilitates an Event Mangement System application, which is essentially a calendar-like application, where people can track various events. This backend facilitates an Event Mangement System application, which is essentially a calendar-like application, where people can track various events.
## Technology ## Technology
The backend uses the [FastAPI](https://fastapi.tiangolo.com/) framework with [Python](https://www.python.org/) 3.12 or higher. To facilitate MongoDB connection, I will be using the [motor](https://pypi.org/project/motor/) library with [Beanie](https://beanie-odm.dev/) object-document mapper (ODM). The project will also contain a Dockerfile and a docker-compose file, which will make starting it very easy and reproducible. The backend uses the [FastAPI](https://fastapi.tiangolo.com/) framework with [Python](https://www.python.org/) 3.12 or
higher. To facilitate MongoDB connection, I will be using the [motor](https://pypi.org/project/motor/) library with
[Beanie](https://beanie-odm.dev/) object-document mapper (ODM). The project will also contain a Dockerfile and a
docker-compose file, which will make starting it very easy and reproducible.
## Installation ## Installation
... > [!TIP]
> Instead of manually installing the project, you can also use the provided `Dockerfile` and `docker-compose.yml` file.
> See the [Docker](#docker) section for more information. This will very likely be the easiest and quickest way to get
> the project up and running. If you're not interested in the docker install, keep reading.
If you only wish to run the project and you're not interested in doing some further development on it, you can simply
use `pip` and `venv` to install all the necessary dependencies:
> [!NOTE]
> Make sure you're in the root directory of the project (the same folder that this README file is in).
```bash
# Create & activate python virtual environment
python -m venv .venv
. .venv/bin/activate
# Install the dependencies
python -m pip install -e .
```
This will only install the runtime dependencies, necessary to actually run the code. (The development dependencies will
not be installed.) The dependencies will be installed into their own isolated virtual environment, which won't interfere
with the system-wide python dependencies.
### For development
This project uses [`rye`](https://rye.astral.sh/), which is a dependency management tool for python. You will need to
install it. (On Arch Linux, you can run `pacman -S rye`.)
Once you get `rye` installed, go to the project's root directory and run:
```bash
rye sync
```
This will install all of the necessary dependencies you'll need to run this project, including the development
dependencies in a virtual environment. To then activate this environment, you can run:
```bash
. .venv/bin/activate
```
## Running
To run the project, make sure you've activated your virtual environment first, then simply execute:
```bash
poe run
```
Note that by default, this will start listening on `localhost:8000`, if you wish to change this, you can use the `--host`
and `--port` flags, like so:
```bash
poe run --host 0.0.0.0 --port 8080
```
(Changing the host from `localhost` to `0.0.0.0` is necessary to make the server accessible from other devices on the
network)
If you wish to run the project in development mode (with auto-reload on change), you can instead use:
```bash
poe run-dev
```
> [!IMPORTANT]
> You will also need to have configured the project first, most notably, you'll need to set a MongoDB connection string.
> Which also obviously means you'll need to have a MongoDB instance running. You can read more about how to configure the
> project in the [Configuration](#configuration) section.
## 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.
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:
```bash
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.
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:
```bash
sudo docker-compose up -d
```
> [!IMPORTANT]
> You will also need to have configured the project first. For docker install though, you don't need to set the MongoDB
> connection string yourself, as the MongoDB instance is running through docker as well, and the connection string is
> 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.
## Configuration
To configure the project, you can either set the environment variables manually or create a `.env` file in the root directory of
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
`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
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).
### Example `.env` file
The `.env` file should look something like this:
```dotenv
DEBUG=0
JWT_SECRET_TOKEN=e51ca69e8d42422c7d2f94bc14e9aaaf294bb55a881354633f5e44f2dc9fde71
MONGODB_URI=mongodb://root:test@localhost:27017/my-cool-database?authSource=admin
```