About ArcanaPDF

AI-Powered 5E compatible character sheet generator.


ArcanaPDF is a personal, free, and open-source project designed to streamline the creation of character sheets for 5E compatible TTRPGs.

The initial idea began in 2023 as an NPC generator for Harvard's CS50P course final project. Back then, the application was quite simple, solely usable via CLI, yet still fun to use!

A year later, I took Harvard's CS50X, where I learned about dev stacks, utilizing Python with the Flask framework, Jinja2 templates, HTML/CSS/JavaScript, and SQL. Upon course completion, I delved into programming to improve and flesh out the NPC generator. It was a nice touch to have a GUI after all 😄.

Artificial intelligence was recently released for public users, and then it hit me: Wouldn't it be great to have an AI agent craft interesting backstories for NPCs? Or even better, to visualize your favorite allies and villains? What a useful tool for DMs that would be, huh? 🤗 Indeed, when REST APIs were made public, implementing those AI features was mind-blowing!

During the development process, as I was adding new features and options to the web app, I realized it could easily be used for character creation instead of just NPC creation. After all, it was becoming too complex and detailed for merely a "poor little NPC."

Are you in the mood to contribute? Feel free to contact me!

How It Works

  • Create your account for free or login as a demo user.
  • Free accounts get 20 AI tokens upon email verification.
  • Demo users don't need to register, but lack AI tokens for AI features.
  • Create a character. You can store up to 10 characters.

GitHub README.md

This page is generated from GitHub ArcanaPDF repository


ArcanaPDF v1.0.0

Archived (October 2026). ArcanaPDF is no longer developed, and this repository is read-only. The app keeps running at https://arcanapdf.onedice.org on the image built from the last commit of production. Its AI features all use OpenAI, with models set in the server's env file, so a retired model can be replaced without a code change (see Maintenance after the archive below).

A character generator tailored for 5E compatible TTRPGs. It creates character sheets in PDF form powered by AI APIs to include interesting backstories, unique portraits, and audio presentations.

Character statistics are determined either randomly or customed by the user.

The application runs either in terminal mode (more convenient for testing purposes) or in browser mode based on Flask microframework.

Available options

Races and Subraces

  • Dragonborn
    • All draconic ancestries
  • Dwarf
    • Hill
  • Elf
    • High
  • Halfling
    • Lightfoot
  • Half-orc
  • Human

Classes and Subclasses

  • Fighter
    • Champion
  • Rogue
    • Thief
  • Wizard
    • Evoker

World Settings

  • User-defined World Settings including further details such as:
    • World Setting Style
    • Nationality
    • Hometown
    • Ethnicity

Appearance

  • User-defined or app-generated character appearance

Attributes (ability scores)

  • User-defined or app-generated ability scores, put on character's attributes either automatically or manually

Identity

  • User-defined character name or app-generated
  • Select between 11 backgrounds:
    • Acolyte
    • Arcane Street Urchin
    • Exiled Diplomat
    • Guild Cartographer
    • Hermetic Alchemist
    • Librarian of the Forgotten Lore
    • Retired Gladiator
    • Sanctuary Healer
    • Sky-faring Trader
    • Subterranean Scout
    • Whispering Oracle
  • All ethical and moral alignments that are 5E compatible according to SRD 5.1

Organization

  • User-defined organization and ability to upload image of heraldry

Weapons

  • All weapons that are 5E compatible according to SRD 5.1

Armor

  • All armor that are 5E compatible according to SRD 5.1

AI-Powered Features

All three use OpenAI as the primary vendor (since 2026-10-19). Each model is an environment variable, with the default in brackets:

  • Backstory: OPENAI_ENGINE_MODEL (gpt-5.6-luna). If OpenAI fails, it falls back to Google Gemini, then the onedice Open WebUI, then Anthropic, in the order set by PRIMARY_AI_SERVICE … QUATERNARY_AI_SERVICE.
  • Portrait: OPENAI_IMAGE_MODEL (gpt-image-2, 1024x1536, medium quality), drawn in the art style the user picks (anime, comic, digital, hyperrealistic, painting or pulp), each spelled out in the prompt in get_portrait.py, with the world setting's aesthetic. If OpenAI fails, it falls back to Stability AI's Stable Diffusion XL.
  • Audio presentation: OPENAI_TTS_MODEL (gpt-4o-mini-tts), narrated in a style matched to the alignment and mixed with background music.

Magic Items

  • All magic items* that are 5E compatible according to SRD 5.1

*Magic Items selection is random, based on an algorimth.

Spells

  • All spells* that are 5E compatible according to SRD 5.1

*Spells selection is random, based on an algorimth.

Skills

  • All skill* that are 5E compatible according to SRD 5.1

*Skill selection is random, based on an algorimth.

More to come options

Races and Subraces

  • All races and subraces included in SRD5.1

Classes and Subclasses

  • All classes and subclasses included in SRD5.1

Custom Spell Selection

Spells will be selected by the user instead of being randomly selected by the web app.


For Contributors

The repository is archived: the sections below describe how the app was developed and deployed, for reference.

Branches

ArcanaPDF used a Git branching strategy based on the Git Flow methodology:

  • development. Where the development work was done, in branches created from it, merged back by pull request.
  • production. For production code. Every push to it deployed https://arcanapdf.onedice.org (see Deployment below).

The staging branch and server were retired on 2026-10-14.

Deployment

A push to production (or a manual run of the CI/CD workflow) built ghcr.io/a-tsagkalidis/arcanapdf/arcanapdf:<commit sha> and ran deploy/remote-deploy.sh on the VPS. That script swaps the arcanapdf-prd container (bound to 127.0.0.1:8080, 1 GB, environment from ~/.env.arcanapdf.production.hetzner, user files in /srv/nas), waits for /healthz and the home page, and rolls back to the previous image if they do not answer. The MySQL container arcanapdf-prd-mysqls is managed separately (deploy/mysql.sh). Deploy access: tools/deploy-access.sh arcanapdf in a-tsagkalidis/onedice-vps.

Maintenance after the archive

An archived repository runs no workflows, so nothing deploys from here any more. The VPS is managed from a-tsagkalidis/onedice-vps, whose monthly AI probe checks that the three OpenAI models still exist and answer.

  • A model is retired: change it in ~/.env.arcanapdf.production.hetzner on the VPS (OPENAI_ENGINE_MODEL, OPENAI_IMAGE_MODEL or OPENAI_TTS_MODEL), then recreate the container on the image it already runs. From a workstation logged in to gh (the token pulls the image from GHCR and never shows):
    img=$(ssh onedice "docker inspect -f '{{.Config.Image}}' arcanapdf-prd")
    { printf 'export IMAGE=%q GHCR_USER=%q GHCR_TOKEN=%q\n' "$img" a-tsagkalidis "$(gh auth token)"
      cat deploy/remote-deploy.sh; } | ssh onedice bash -s
    
  • OpenAI credit runs out: backstories fall back to the other vendors, while portraits fall back to Stability AI only as long as its credits last. Spoken presentations have no fallback.

Setup

In general it is recommended to use a Linux Ubuntu machine as your development environment to be aligned with production. Production runs the image built from this repository's dockerfile (Python 3.11 on Debian bookworm).

Developers run the source code in a container built from that same dockerfile, with the repository mounted into it, or in a Python venv (python3 -m venv .venv && .venv/bin/pip install -r requirements.txt). (The former Docker Hub image atsagkalidis/arcanapdf-dev was retired in October 2026.)

The following guide is to support ONLY Linux Ubuntu environments that use the containerized setup.

Containerized setup

1. Install and enable Docker

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo systemctl status docker

2. Download ArcanaPDF GitHub repository

git clone https://github.com/a-tsagkalidis/arcanapdf.git

3. Build the developer Docker image

From the repository root, build the image from the repository's own dockerfile. Rebuild it whenever requirements.txt or the dockerfile change.

sudo docker build -t arcanapdf-dev -f dockerfile .

4. Inject environment variables

ArcanaPDF uses a .env file to get the *environment variables that are needed for the application to operate. The repository stores it encrypted as .env.arcanapdf.development.enc (with .env.arcanapdf.production.hetzner.enc and .env.arcanapdf.github.enc). The owner holds the passwords. With the three of them exported as DEV_ENV_DEC_PWD, PRD_HTZ_ENV_DEC_PWD and GH_ENV_DEC_PWD, decrypt (or, with -enc, encrypt) all three from the repository root:

bash static/scripts/dotenv_cryptography.sh -dec

The script refuses to run if a password is missing, and keeps the plain file as it was if a password is wrong.

*In case you want to use your own .env file you can create one by following the steps in section Create your own .env file that is presented at the bottom of this README.md file.

5. Run the app through the container

While you are in the repository root directory at the development branch run the container giving the following *command:

sudo docker run -it --rm --name 'arcanapdf-dev-environment' -p 127.0.0.1:5000:5000 -v "$(pwd)":/app arcanapdf-dev sh -c

*It is recommended to make an alias of this command in ~/.bashrc (Bash) or $profile (PowerShell) for your convenience.

Running this command is going to partially start the application, since it runs the container which prompts to specify more command line arguments. For example if you want to start the application in a browser with debugging mode then you must pass the 'python3 app.py --webapp --debug' argument to the container command as follows:

sudo docker run -it --rm --name 'arcanapdf-dev-environment' -p 127.0.0.1:5000:5000 -v "$(pwd)":/app arcanapdf-dev sh -c 'python3 app.py --webapp --debug'

Always pass --webapp when running the web app (outside the container too: python3 app.py --webapp --customprint --debug). Without it, some errors are swallowed in development and show only as a later NoneType error.

Run the previous command and ArcanaPDF will start in the development server. Flask server will populate something like this:

* Serving Flask app 'app'
* Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
* Running on all addresses (0.0.0.0)
* Running on http://127.0.0.1:5000
* Running on http://172.17.0.2:5000
Press CTRL+C to quit
* Restarting with stat
* Debugger is active!
* Debugger PIN: 684-058-015

Copy and paste the IP address http://127.0.0.1:5000 into your web browser for the graphical interface to be displayed.

Now you can start coding and the changes will be reflected in the web app that is running locally into your browser.

6. Coding and adding features

The repository is archived and accepts no changes. To build on ArcanaPDF, fork it.


Using CLI arguments

For our convenience let's assume that we aliased the developer Docker container command as devenv by adding the following line in ~/.bashrc file.

alias devenv='sudo docker run -it --rm --name arcanapdf-dev-environment -p 127.0.0.1:5000:5000 -v "$(pwd)":/app arcanapdf-dev sh -c'

Initially you should check all available CLI arguments which can be given to the program.

devenv 'python3 app.py --help'

Common running modes

1. Run the app in terminal mode for testing purposes with random inputs and pauses so you can check terminal stdout easier

devenv 'python app.py --terminalmode --customprint --pauseprogram'

2. Run the app in terminal mode for testing purposes with prompted inputs

devenv 'python app.py --terminalmode --customprint --promptuser'

3. Run batches in terminal mode for testing purposes

source static/scripts/devenvbatchtimes.sh INT* --terminalmode --customprint

*where INT enter desired number of times that the application is going to run.

4. Run the app in web app mode for testing purposes

devenv 'python app.py --webapp --customprint --debug'

*To create AI generated content using API functionalities then add the following arguments in the previous commands:

  • --backstory
  • --portrait
  • --presentation

Valid Command Line Arguments and their fucntionality

Argument Functionality Description
-bs, --backstory Get an AI-generated backstory
-cp, --customprint Print output in terminal
-d, --debug Run flask in debug mode
-fp, --freeportrait Web scrap free portrait (deprecated)
-l, --limiter Run flask in limiter mode
-ntf, --notxtfile Prevents program from storing the txt
-p, --portrait Get an AI-generated portrait
-pp, --pauseprogram Runs the program with pauses
-pr, --presentation Get an AI-generated mp3 presentation
-ptj, --pngtojpg Converts png to jpg and saves TTI prompt
-pu, --promptuser prompt the user for value entries
-tm, --terminalmode Runs the program solely in terminal
-wa, --webapp Runs combination of arguments for flask

Check output for debugging

PDF, TXT, MP3, and PNG files are stored in static/dev/flask/usr path. When you use the app in terminal mode all the output files are stored in user 0 - so expect some output in static/dev/flask/usr/0 path.

In case you're using the app in web app mode then the subdirectory integer in the usr folder corresponds to the user_id that is given in the SQLite database.


Create your own .env file [optional]

The .env file must be named as .env.arcanapdf.development and placed in the root directory of the repository. In case you didn't receive a password to decrypt .env.arcanapdf.development.enc file you can create the .env file by yourself and use your very own API keys.

Non-sensitive environment variables

You can safely copy-paste the following environment variables to your .env.arcanapdf.development file

  • DEV_WEBSITES_PORT=5000
  • DEV_WEBSITES_FQDN=http://127.0.0.1
  • DEV_SQL_ENGINE=sqlite:///arcanapdf.db
  • DEV_FREE_AI_TOKENS=20
  • DEV_MAX_CHARACTERS_STORED=10
  • DEV_MOUNT_PATH=static/dev/flask
  • DEV_SECRET_KEY=<generate one: python3 -c 'import secrets; print(secrets.token_hex(32))'>
  • DEV_REDIS_HOST=localhost
  • DEV_REDIS_PORT=6379
  • PRIMARY_AI_SERVICE=openai
  • SECONDARY_AI_SERVICE=gemini
  • TERTIARY_AI_SERVICE=ondillm
  • QUATERNARY_AI_SERVICE=anthropic
  • OPENAI_ENGINE_MODEL=gpt-5.6-luna
  • OPENAI_IMAGE_MODEL=gpt-image-2
  • OPENAI_TTS_MODEL=gpt-4o-mini-tts
  • GOOGLE_GEMINI_ENGINE_MODEL=gemini-3.1-flash-lite
  • ANTHROPIC_ENGINE_MODEL=claude-haiku-5-5

Sensitive environment variables

ArcanaPDF app uses the following services:

  • OpenAI API (backstories, portraits and presentations)
  • Google Gemini API, the onedice Open WebUI and Anthropic API (backstory fallbacks)
  • Stability API (portrait fallback)
  • Brevo Email Services SMTP client

You can create your own API keys and other sensitive environment variables and add them in your .env.arcanapdf.development file according to the following table.

Service Environment Variable Name Example Variable Value
OpenAI API DEV_OPENAI_API_KEY <your OpenAI API key>
Google Gemini API DEV_GOOGLE_GEMINI_API_KEY <your Gemini API key>
Anthropic API DEV_ANTHROPIC_API_KEY <your Anthropic API key>
Stability API DEV_STABILITY_API_KEY <your Stability API key>
Brevo SMTP Server DEV_MAIL_SERVER smtp-service.example.com
Brevo SMTP User DEV_MAIL_USERNAME <your SMTP login>
Brevo SMTP Pass DEV_MAIL_PASSWORD <your SMTP password>