diff --git a/README.md b/README.md index 2d88585..563a7da 100644 --- a/README.md +++ b/README.md @@ -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 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](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 -... +> [!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 +```