avrae

Avrae is a bot to facilitate running Dungeons & Dragons 5e online over Discord. This project is the backend to serve avrae.io.

You can join the Avrae Development Discord here!

Requirements

• Python 3.10+
• MongoDB server
• Redis server

See the README in avrae/avrae for additional instructions and links to dependencies.

Running

Configuration

The development config defaults to the MongoDB/Redis servers run by Avrae Docker Compose.

1. Copy docker/config-development.py to config.py.
2. The dev config should point to the services exposed by the Avrae docker-compose file. If necessary, set the environment variables MONGO_URL and REDIS_URL to override connection strings.
3. Set the DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, and DISCORD_BOT_TOKEN environment variables to the values for your application, found in the Discord Developer Portal.
4. Set the JWT_SECRET env var to any value of your choice.

Env Var Overview

• MONGO_URL - Override connection string to MongoDB, defaults to exposed instance from avrae/avrae docker compose
• REDIS_URL - Override connection string to Redis, defaults to exposed instance from avrae/avrae docker compose
• DISCORD_CLIENT_ID - Discord application Client ID (Dev Portal -> Application -> OAuth2)
• DISCORD_CLIENT_SECRET - Discord application Client Secret (Dev Portal -> Application -> OAuth2)
• DISCORD_BOT_TOKEN - Discord application Bot User Token (Dev Portal -> Application -> Bot)
• JWT_SECRET - Used to sign JWTs issued by the service
• ELASTICSEARCH_ENDPOINT (optional) - Used to specify URL of an ElasticSearch instance for Alias Workshop

ElasticSearch

The Avrae service requires ElasticSearch for some features (e.g. searching alias workshop collections). You should either set up a dev ElasticSearch instance on AWS, or run an openElasticSearch distro.

Whichever you choose, set the ELASTICSEARCH_ENDPOINT env var. The service will work without this set, but Alias Workshop endpoints might have undefined behaviour.

Running locally

1. Create a virtual environment: python3 -m venv venv.
2. Activate the venv: source venv/bin/activate on Unix (bash/zsh), venv\Scripts\activate.bat on Windows.
3. Install the required Python packages: pip install -r requirements.txt.
4. Run the app: python -m flask run.

The service should now be accessible at http://localhost:5000.

Should you have authentication errors and DB not loading locally, you can update line 38 in app.py to the below.

app.mdb = mdb = PyMongo(app, config.MONGO_URL).cx["avrae"]

Running locally with Docker

1. Build the Docker image: docker build -t avrae-service:latest --build-arg ENVIRONMENT=development ..
2. Run the Docker image: docker run -p 58000:8000 avrae-service:latest.

The service should now be accessible at http://localhost:58000.

Running in production

1. Build the Docker image: docker build -t avrae-service:latest.
2. Deploy it in whatever fashion your production environment requires.

The service should now be accessible at http://IP.ADDRESS:8000.

Committing, Formatting, and Linting

Avrae uses Black to format and lint its Python code. Black is automatically run on every commit via pre-commit hook, and takes its configuration options from the pyproject.toml file.

The pre-commit hook is installed by by running pre-commit install from the repo root. The hook's configuration is governed by the .pre-commit-config.yaml file.

Dependencies

In order to run pre-commit or black, they must be installed. These dependencies are contained within the requirements.txt file, and can be installed like so:

(venv) $ pip install -r requirements.txt