Jambo Docs

Appearance

Quickstart ​

Introduction ​

Howdy, how's the weather?

These docs are also available in the docs/ folder of the project, it's vitepress powered and can be served locally by using the following command in that directory.

bash
pnpm run docs:dev

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

Here's the PostMan collection: Run In Postman

Installation ​

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

I have provided a Docker Compose for the easiest deployment.

Prerequisites ​

  • Docker - You need docker installed.

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

bash
docker-compose up

This will spin up all the needed containers and the default django-rest-framework API is accessible via http://localhost:{port}/api/. The port is determined by whether it's in docker or not. (Should be absent for docker)

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 ​
bash
chmod +x run.sh && ./run.sh
Windows ​
shell
./run.bat

INFO

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. See this

shell
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

shell
python manage.py test

DANGER

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