event-management-backend/README.md

Backend for the Event Management System project

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

This backend facilitates an Event Mangement System application, which is essentially a calendar-like application, where people can track various events.

Technology

The backend uses the FastAPI framework with Python 3.12 or higher. To facilitate MongoDB connection, I will be using the motor library with Beanie 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

Tip

Instead of manually installing the project, you can also use the provided Dockerfile and docker-compose.yml file. See the 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).

# 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, 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:

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:

. .venv/bin/activate

Running

To run the project, make sure you've activated your virtual environment first, then simply execute:

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:

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:

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 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 and Docker compose installed. Once you have that, you can run:

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:

sudo docker up --build

If you wish to run the containers in the background, you can add the -d flag:

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 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:

DEBUG=0
JWT_SECRET_TOKEN=e51ca69e8d42422c7d2f94bc14e9aaaf294bb55a881354633f5e44f2dc9fde71
MONGODB_URI=mongodb://root:test@localhost:27017/my-cool-database?authSource=admin