https://open5e.com
A JSON API for the D&D 5e ruleset
Table of contents generated with markdown-toc
Open5e is a community project driven by a small number of volunteers in their spare time. We welcome any and all contributions! Please join our Discord to help out: https://discord.gg/9RNE2rY or check out the issue board if you'd like to see what's being worked on!
The API uses the Django REST Framework for it's browsability and ease of use when developing CRUD endpoints. It uses django's default SQLite database, and pulls the data from the /data
directory.
Pipenv is used to install all required packages from the Pipfile
at the project root. Use the following command after cloning the project or switching branches.
pipenv install --dev
Crate a local database and import game content.
pipenv run python manage.py quicksetup --noindex
To make sure the API is always using your updated code, this command must be run again if:
To use the search function, you must build the search index by running the above command without the --noindex
flag.
pipenv run python manage.py quicksetup
Run the server locally. This server is only for development and shall not be used in production. The server will be available at http://localhost:8000
.
pipenv run python manage.py runserver
If you need to run the server on another port, add the port number as an argument.
pipenv run python manage.py runserver $PORT
After completing a build, you can generate an OAS file to be used by another application.
pipenv run ./manage.py generateschema --generator_class api.schema_generator.Open5eSchemaGenerator > openapi-schema.yml` to build the OAS file.
See contribution guide.
Tests are located in the api/tests
directory. These should be run before pushing new changes to the main repository. These tests require that the api is running at http://localhost:8000
.
pipenv run pytest
Approval tests are run against the approved files in api/tests/approved_files
as *.approved.*
. If a test fails then the recieved input will be stored in a *.recieved.*
file. If you wish to approve the changes, replace the old approved file with the recieved file.
Recieved files shall not be included in the git repo.
This deployment has been tested using DigitalOcean Apps with Docker Hub.
To start up the server from scratch on a droplet:
git pull https://github.com/open5e/open5e-api
export SECRET_KEY=a_new_secret_key
export SERVER_NAME=whatever.yourdomain.com
cd open5e-api/
docker-compose up
PORT
with the value 8888
.SERVER_NAME
with the Railway-provided domain or add your own. With docker installed, you can build the project with provided Dockerfile
docker build
This docker app can then be deployed with any provider.