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 byPRIMARY_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 inget_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.hetzneron the VPS (OPENAI_ENGINE_MODEL,OPENAI_IMAGE_MODELorOPENAI_TTS_MODEL), then recreate the container on the image it already runs. From a workstation logged in togh(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> |