Jambo

Introduction

Chosen stack:
    1. Django - Django Rest Framework
    2. Vitepress - For Documentation
    3. Docker & Shell - For Containerization
    4. Postgres - For Database
    5. Redis - For Caching
    6. GitHub - For Version Control
    7. GitHub Actions - For Deployment (Docs only)
    8. Nginx - For Reverse Proxy
    9. PostMan - Tool to help with API documentation

A thorough documentation of the API is online here.

Here's the PostMan collection:

Alternatively, the docs/ folder is vitepress powered and can be served locally by using the following command in that directory.

pnpm run docs:dev

This is done automagically when running the server and is accessible via http://localhost/docs. You may as well just skim the raw markdown files in the docs/ folder should you wish to.

Installation

You can install this project in two ways, either via Docker or via Shell Scripting.

Docker (Recommended)

I have provided a Docker Compose for the easiest deployment. This however is only suitable if your computer is powerful enough to run the containers.

Prerequisites

• Docker - You need docker installed.

Then run the following command in the root directory of the project.

docker-compose up

This will spin up all the needed containers and the default django-rest-framework API is accessible via http://localhost/api/.

Shell Scripting

I have also provided a shell script for easy non-docker deployment. This time however, you need to have the following installed:

Prerequisites

• Python 3 - You need at least python 3.10 installed. Due to the use of type hints
• Node - You need node installed. This is for the documentation.
• Postgres - You need postgres installed. Make sure there exists a database whose URI string should be added to the .env.
• Redis - Optional, could be run as a container, wsl or vm
• Nginx is not implemented outside docker due to known issues - Skip

Then run the following command in the root directory of the project.

Linux

chmod +x run.sh && ./run.sh

Windows

./run.bat

NB: You may run into an Execution-Policy error on Windows, in that case, you need to execute the following command in an admin window before retrying the step above in a fresh window again.

Set-ExecutionPolicy RemoteSigned

Secrets

Environment variables should be stored in a .env and a .env.docker(used in docker) file in the root directory of the project. You can rename the .env.example file to .env and .env.docker.example to .env.docker for containerized environments, then fill in the necessary details. It's rudimentary and self-documented with comments.

You will notice that if the app will create a SECRET_KEY for you and store it in the .env file if you don't provide one. This is not recommended for production, so always define a SECRET_KEY in your .env file or environment. The SECRET_KEY is used for hashing and encryption. It's just a long random string, can be anything.

Testing

I have included tests to ensure the API is working as expected. Running tests can be done via the following command once the server is up

python manage.py test

Note Do not use PyCharm's built in test runner or debugger as it won't initialise settings and environment variable therein properly