LarpManager

LarpManager is a free platform to manage live-action roleplaying (LARP) events.

If you don't want to self-host, you can use the free hosted instance at: https://larpmanager.com

---

Documentation

• Features and Permissions Guide - How to create new features, views, and permissions
• Roles and Context Guide - How to structure views with context and understand role-based permissions
• Configuration System Guide - How to add customizable settings without modifying models
• Localization Guide - How to write translatable code and manage translations
• Playwright Testing Guide - How to write and run end-to-end tests
• Feature Descriptions - Complete reference of all available features
• Developer Instructions - Architecture, commands and best practices
• Contributing - How to contribute to the project
• Deployment - Production deployment instructions

---

Licensing

LarpManager is distributed under a dual license model:

• Open Source (AGPLv3): Free to use under the terms of the AGPLv3 license. If you host your own instance, you must publish any modifications and include a visible link to larpmanager.com on every page of the interface.

• Commercial License: Allows private modifications and removes the attribution requirement. For details or licensing inquiries, contact commercial@larpmanager.com.

Refer to the LICENSE file for full terms.

---

Quick start (Docker)

If you want an easy and fast deploy, set the environment variables see below for instructions on their values:

cp .env.example .env

Now time for the docker magic (see below for instructions on installing it):

docker compose up --build

Now create a super user:

docker exec -it larpmanager python manage.py createsuperuser

Security recommendation: It is strongly recommended to enable two-factor authentication (TOTP) for all superuser and staff accounts on the Django admin backend (/admin/). After your first login, go to Home / OTP TOTP devices in the admin panel and configure a TOTP device using an authenticator app (e.g. Google Authenticator, Authy, Bitwarden). Once a device is enrolled, the next admin login will require OTP verification.

Go to http://127.0.0.1:8264/admin/larpmanager/association/, and create your Organization. Put as values only:

• Name: you should get it;
• URL identifier: put def;
• Logo: an image;
• Main mail: the main mail of the organization (duh)

Leave the other fields empty, and save.

Now expose the port 8264 (we wanted a fancy one) to your reverse proxy of choice for public access. Example configuration for nginx, place this code in /etc/nginx/sites-available/example.com:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8264;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Now create the symlink:

ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Now you're ready for liftoff!

---

Windows user: On some cases the docker fails to start up, you might want to try

dos2unix scripts/entrypoint.sh

---

If you want some more extra juicy stuff, you can set an automatic execution of

docker exec -it larpmanager python manage.py automate

This command performs a bunch of stuff related to advanced features; it should be run each day (cron?), when low traffic is expected (night?). You should combine it with the daily backup of pgdata and media_data volumes.

---

In the future, if you want to pull the latest changes of the repo, go with:

git pull origin main
docker exec -it larpmanager scripts/deploy.sh

It will perform a graceful restart.

---

Cloud recommendations

Suggested baseline for cloud VMs:

• OS: Ubuntu 24.04 LTS (required for Python 3.12)
• Instance type: burstable instance to handle activity spikes

Some typical options could be:

• EC2: t3.small / t3.medium
• GCP: e2-small / e2-medium
• Azure: B1ms / B2s

---

Environment variables

Set those values:

• GUNICORN_WORKERS: Rule of thumb is number of processors * 2 + 1
• SECRET_KEY: A fresh secret key, you can use an online tool
• ADMIN_NAME, ADMIN_EMAIL: Set your own info
• DB_NAME, DB_USER, DB_PASS, DB_HOST: The database will be generated based on those values if it does not exists
• TZ: The base timezone of the server
• GOOGLE_CLIENTID, GOOGLE_SECRET: (Optional) If you want Google SSO, follow the django-allauth guide
• RECAPTCHA_PUBLIC, RECAPTCHA_PRIVATE: If you want recaptcha checks, follow the django-recaptcha guide

---

Docker installation

To install everything needed for the quick setup, install some dependencies:

sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common

add docker's repo:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

finally, install Docker:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

run it:

sudo systemctl start docker
sudo systemctl enable docker

---

Portainer deployment

Portainer lets you deploy and manage the stack through a web UI instead of the CLI.

Prerequisites

Portainer must already be installed and running. If not, follow the official install guide.

Deploy the stack

1. In Portainer, go to Stacks -> Add stack
2. Name it larpmanager
3. Choose Repository and point it to your local clone of this repo, or use Web editor and paste the contents of docker-compose.yml
4. Scroll down to Environment variables and add the values listed in .env.example (see Environment variables for descriptions)
5. Click Deploy the stack

Portainer pulls images, builds the app container, and starts all services.

First-time setup

Once the stack is running, open a console into the app container:

1. Portainer -> Containers -> click larpmanager -> Console -> Connect
2. Run:

python manage.py createsuperuser

3. Browse to http://your-server-ip:8264/admin/larpmanager/association/ and create your organization (Name, URL identifier def, Logo, Main mail -- leave everything else empty).

Verify everything is working

• App responds: browse to http://your-server-ip:8264/ -- you should see the LarpManager login page
• Admin works: browse to http://your-server-ip:8264/admin/ and log in with the superuser you created
• Static files load: CSS and images render correctly (served by nginx via the static_data volume)
• Media uploads work: upload a logo in the association admin; it should save without errors

Expose on a specific IP or change the port

By default nginx binds port 8264 on all interfaces (0.0.0.0). To restrict to a specific IP, edit the nginx ports line in the stack editor:

nginx:
  ports:
    - "192.168.1.50:8264:80"   # only this IP accepts connections

Replace 192.168.1.50 with your server's LAN or public IP. To use a different host port, change the first number (e.g. "80:80").

Use a reverse proxy for a domain name

To serve on a domain with standard ports (80/443), run a reverse proxy as a separate Portainer stack (nginx, Traefik, Caddy, etc.). Example minimal nginx config:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8264;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

With this in place, remove the ports section from the nginx service in the LarpManager stack so it is no longer exposed directly.

Day-to-day operations via Portainer

Task	How
View logs	Containers -> larpmanager -> Logs
Run management commands	Containers -> larpmanager -> Console
Update to latest code	Pull repo on host, then Console: scripts/deploy.sh
Daily automation	Console: python manage.py automate (schedule via host cron or Portainer scheduled jobs)
Backup data	Volumes -> download pgdata and media_data

---

Local Setup

The typical, recommended setup is to have:

• On a server the production instance, managed with docker, with the real user data, CI pipeline, automated backup and all other devops best practices;
• On your local machine, a development instance, managed with dedicated system installations, dummy test database and local development server.

Here are the step for a local setup on your machine, required for both Develop and Contributing.

Requirements:

• Python 3.12 or higher
• Ubuntu 24.04 LTS recommended

For a Debian-like system: install the following packages:

# On Ubuntu 24.04 LTS
sudo apt install python3.12 python3.12-venv python3.12-dev python3-pip redis-server git \
  postgresql postgresql-contrib libpq-dev nodejs build-essential libxmlsec1-dev \
  libxmlsec1-openssl libcairo2-dev pkg-config

# On Ubuntu 22.04 or older (requires deadsnakes PPA for Python 3.12)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev python3-pip redis-server git \
  postgresql postgresql-contrib libpq-dev nodejs build-essential libxmlsec1-dev \
  libxmlsec1-openssl libcairo2-dev pkg-config

Install uv (fast Python package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh

Create and activate a virtual environment:

uv venv
source .venv/bin/activate

Install Python dependencies:

uv pip install -r pyproject.toml

Install and activate LFS to handle big files:

sudo apt install git-lfs
git lfs install
git lfs pull

Database Setup

Create the PostgreSQL database and user:

sudo -u postgres psql

Then run the following SQL commands (default credentials: user larpmanager, password larpmanager):

CREATE DATABASE larpmanager;
CREATE USER larpmanager WITH PASSWORD 'larpmanager';
ALTER USER larpmanager CREATEDB;  -- Required for running tests
ALTER DATABASE larpmanager OWNER TO larpmanager;
GRANT ALL PRIVILEGES ON DATABASE larpmanager TO larpmanager;
\q

Note: The CREATEDB privilege is required for running tests, as pytest creates temporary test databases.

Django Configuration

1. Copy main/settings/dev_sample.py to main/settings/dev.py:

   cp main/settings/dev_sample.py main/settings/dev.py

2. The default database settings should work with the setup above. If you used different credentials, update the DATABASES section in main/settings/dev.py.

3. In SLUG_ASSOC, put the slug of the organization that will be loaded (default is def).

Frontend Dependencies

Install npm modules for frontend functionality:

cd larpmanager/static
npm install
cd ../..

Testing Setup

Install Playwright browsers for end-to-end tests:

playwright install

Develop

The codebase is based on Django; if you're not already familiar with it, we highly suggest you to follow the tutorials at https://docs.djangoproject.com/.

1. Follow the steps outlined in Local setup for setting up your local development instance

2. Run migrations to initialize the database:

   python manage.py migrate

3. Load the initial test data:

   python manage.py reset

(Since this command is dangerous, we added a check to prevent it to be executed on main branch; to execute, just create a new branch before)

4. Now you can run the local server for manual testing and debugging:

python manage.py runserver

5. You can use default users "orga@test.it" and "user@test.it", both with password "banana"

---

Contributing

Thanks in advance for contributing! Here's the steps:

1. Follow the steps outlined in Local setup for setting up your local development instance

2. Install and activate pre-commit:

   uv pip install pre-commit
   pre-commit install

3. In the main/settings/dev.py settings file, add a DEEPL_API_KEY value. You can obtain a API key for the DeepL API Free (up to 500k characters monthly) here.

4. Create a new branch:

   git checkout -b prefix/feature-name

   For the prefix please follow this naming strategy:

   • hotfix for urgent fixes in production
   • fix for correction to existing functions
   • feature for introducing / upgrading functions
   • refactor for code changes not related to functions
   • locale for changes in translation codes.

5. When you'are ready with the code changes, to make sure that all entries have been translated (default language is English), run

   ./scripts/translate.sh

   This will updated all your translations, have correct the untranslated / fuzzy ones with Deepl API. In the terminal, take some time to review them before proceeding.

6. If you're creating a new feature, write a playwright test suite that covers it. Look in the larpmanager/tests folder to see how it's done. (Standard users are "orga@test.it" and "user@test.it", both with password "banana"). Run

   ./scripts/record-test.sh

   To run an instance of playwright that will record all your actions, in code that can later be inserted into the test.

   • If you wish to expand an existing test, you can place a page.pause() at the end of it, and then run

    PWDEBUG=1 pytest larpmanager/tests/playwright/ability_px_test.py --headed -s

   It will execute the text up untile the pause, so you can record the actions after it (remember to remove the page.pause() before committing)

7. If you're changing the model or the fixtures, run:

   python manage.py dump_test

   to update the dump used by tests and ci.

8. Before pushing make sure that all the tests passes using:

   ./scripts/test.sh [workers] (default: 4 workers)

   Note that the tests will take some time to complete.

9. When you're ready to push your new branch, run

   ./scripts/upgrade.sh

   This will execute some helpful activities like making sure you're updated with main branch, deleting old local branches, and other small things like that.

10. Go and open a new pull request. Make sure to explain clearly in the description what's happening.

Guidelines

Pull Requests should include only the minimal changes necessary to achieve their goal. Avoid non-essential changes such as refactoring, renaming, or reformatting, unless explicitly approved beforehand.

This helps keep code reviews focused, reduces merge conflicts, and maintains a clean commit history. If you believe a refactor is needed, please open an issue or start a discussion first to get approval.