All Time Wrestling RPG

All Time Wrestling (ATW) RPG is a web-based wrestling RPG simulator that allows you to book shows, manage wrestlers, and generate AI-narrated matches.

Table of Contents

• Getting Started
• Features
• Show Management
  • Segment Ordering and Main Event
  • AI Narration
• Segment Rules
  • Bump Addition
• Development
• Running the Application
• Executable JAR
• Native Desktop Installers
• Docker
  • Prerequisites
  • Building the Docker Image
  • Running the Application with Docker
• Running with a Standalone Tomcat Server
• Configuring Tomcat for HTTPS
• HTTPS over LAN with Caddy (QR Code Sharing)
• Code Quality
• Code Coverage
• Code Formatting
• Security
• Maintenance
• Dependency Security
• NVD API Key Configuration
• Security Workflows
• Running Security Scans Locally
• Security Policies
• Development Workflow
• Pull Request Labeling

Getting Started

To start the application in development mode, import it into your IDE and run the Application class.

You can also start the application from the command line by running:

./mvnw

The application will be available at http://localhost:8080/atw-rpg.

For project-specific startup instructions, see the Application Startup Guide. For instructions on how to add and manage game content (wrestlers, cards, sets), see the Content Management Guide. For general Vaadin information, see the Vaadin Getting Started Guide.

Features

Show Management

Segment Ordering and Main Event

You can now reorder segments within a show and designate one segment as the main event. This provides greater control over the flow and narrative of your shows.

How to use:

1. Navigate to the Show Details page: From the "ShowList" view, click on a show to open its details.
2. Drag and drop to reorder: In the "Segments" grid, you can now drag and drop segment rows to change their order.
3. Set the main event: Each segment row has a "Main Event" checkbox. Select the checkbox for the segment you want to mark as the main event.

AI Narration:

The AI narration service is aware of the segment order and which segment is the main event. It also has access to the results and narration of previous segments. This allows the AI to generate more context-aware and compelling narrations that build on events from earlier in the show.

Ranking System

The ranking system has been updated to provide a more dynamic and inclusive contender pool. Wrestlers are primarily ranked based on their fan count, with higher fan counts generally indicating higher ranks.

Crucially, wrestlers who have surpassed the typical fan cap for a given title's tier are no longer excluded from its rankings. This means a top-tier wrestler (e.g., a Main Eventer) can still appear in the contender list for a mid-card title if they meet the minimum fan requirements for that title, allowing for more diverse and strategic championship pursuits.

Fan Adjudication

Fan acquisition and loss mechanics have been refined to ensure a more balanced and realistic progression for wrestlers:

• Gaining Fans: Wrestlers gain fans by winning matches and delivering successful promos. The amount of fans gained can be influenced by the wrestler's current tier, with higher tiers potentially experiencing diminishing returns to prevent runaway fan inflation.
• Losing Fans: A significant change is the introduction of fan loss for match losers. Previously, all participants would gain fans. Now, wrestlers who lose a match may experience a decrease in their fan count, or at best a minimal gain, depending on the match quality and their performance. This adds a layer of consequence to match outcomes and helps to naturally regulate fan numbers across the roster.

Season Management

At the end of each season, you have the option to perform a "soft reset" of your roster's fan standings and tier definitions. This helps keep the game balanced and provides a fresh start for the new season. These actions are available in the Season Settings view.

Fan Recalibration

The fan recalibration process adjusts wrestler fan counts to prepare for the next season:

• Icons Demoted: Wrestlers in the "Icon" tier are demoted to the "Main Eventer" tier.
• Fan Count Adjustment: All wrestlers, including the demoted Icons, will have their fan counts recalibrated to the minimum fan count required for their new or existing tier. This ensures that wrestlers are appropriately positioned within their tiers at the start of a new season.

This process helps to prevent fan counts from becoming excessively inflated over time and ensures that the top tiers of the roster remain competitive.

Tier Boundary Reset

You can reset the fan count boundaries for each wrestler tier back to their default values. This is useful if you have made adjustments to the tier boundaries during a season and want to revert to the standard configuration for the next season.

This ensures that the progression through the tiers remains consistent from season to season, unless you choose to make specific adjustments.

Full Fan Count Reset

For a more drastic reset, you can use the "Full Fan Count Reset" option. This will reset all wrestler fan counts to 0 and their tier to ROOKIE. This is useful for starting a completely new game or when you want to level the playing field entirely.

Drama Event Management

The application features a drama event system that periodically generates random events affecting wrestlers (e.g., backstage incidents, social media drama, injuries).

Configuration:

The drama event scheduler is configured in the application.properties file.

# Enable or disable the drama event scheduler
drama.events.scheduler.enabled=true

# Frequency of event generation in milliseconds (default: 7 days)
drama.events.scheduler.rate=604800000

When enabled, the system will periodically select a random number of wrestlers and generate drama events based on weighted probabilities.

Segment Rules

Bump Addition

You can now configure segment rules to automatically add bumps to participants. This allows for more granular control over the physical toll that different types of matches have on wrestlers.

How to use:

1. Navigate to the Segment Rule List page: From the main menu, select "Segment Rules".
2. Create or Edit a Segment Rule: Click the "Create Segment Rule" button or the edit icon on an existing rule.
3. Select the Bump Addition option: In the edit dialog, you will see a "Bump Addition" dropdown. You can select one of the following options:
   • NONE: No bumps are added to any participants.
   • LOSERS: Bumps are added to all losers of the segment.
   • WINNERS: Bumps are added to all winners of the segment.
   • ALL: Bumps are added to all participants of the segment.
4. Save the Segment Rule: Click the "Save" button to save your changes.

When a segment with the configured rule is adjudicated, bumps will be added to the participants according to the selected option.

Development

This section contains information for developers contributing to the project.

Running the Application

To build the application in production mode, run:

./mvnw -Pproduction package

This will produce an executable JAR in the target/ directory.

Executable JAR

The application can be run directly as a standalone executable JAR. This is the recommended way for most users as it includes an embedded Tomcat server.

1. Build the JAR:

   ./mvnw clean package -DskipTests
   

2. Run the JAR:

   java -jar target/all-time-wrestling-rpg-*.jar
   

The application will be available at http://localhost:8080/atw-rpg.

Native Desktop Installers

For non-technical users, you can generate native installers (DMG for macOS, DEB for Linux, MSI for Windows) that bundle a minimal Java runtime and include system tray integration and automatic browser launching.

1. Build the Installer:

   ./mvnw clean package -Pproduction,desktop -DskipTests
   

2. Find the Installer: The generated installer will be located in target/dist/.

Portable Distribution (Zero-Install)

If you don't want to install the game, you can use the portable ZIP distribution.

1. Build the Portable ZIP:

   ./mvnw clean package -Pproduction,portable -DskipTests
   

2. Run the Game: Unzip the archive in target/ and run start-windows.bat, start-macos.sh, or start-linux.sh.

GraalVM Native Image

For the fastest startup and lowest memory usage, you can build a native executable.

1. Build the Native Image:

   ./mvnw clean package -Pproduction,native -DskipTests
   

   Note: Requires GraalVM JDK with native-image installed.

Docker

This project can be built and run using Docker.

Prerequisites

• Docker installed on your machine.

Building the Docker Image

1. Build the project using Maven:

   ./mvnw clean install -DskipTests
   

2. Build the Docker image:

   docker build -t all-time-wrestling-rpg .
   

Running the Application with Docker

To run the application using Docker, you need to provide the required environment variables and mount a volume to persist the database.

1. Run the Docker container:

   docker run -p 9090:9090 \
   -v /path/to/your/data:/data \
   -e AI_GEMINI_API_KEY="your_gemini_key" \
   -e AI_OPENAI_API_KEY="your_openai_key" \
   -e AI_CLAUDE_API_KEY="your_claude_key" \
   all-time-wrestling-rpg
   

   • -p 9090:9090: Maps the container's port 9090 to the host's port 9090.
   • -v /path/to/your/data:/data: Mounts a directory from your host machine to the /data directory inside the container. This is where the H2 database file will be stored, ensuring data persistence. Replace /path/to/your/data with the absolute path on your host machine.
   • -e: Sets the environment variables required for the AI services. Mandatory Security Note: Sensitive values (API keys, tokens) are not stored in the Docker image and must be provided at runtime using this flag or an --env-file.
   • AI settings can be configured via environment variables or in-application in the AI Settings view. Keys set there are stored in the database and survive restarts.

AI Environment Variables

The following environment variables can be used to configure AI services:

• AI_TIMEOUT: Request timeout in seconds (default: 300).
• AI_PROVIDER_AUTO: Automatically select the first available provider (default: true).
• AI_OPENAI_ENABLED: Enable OpenAI (default: false).
• AI_OPENAI_API_KEY: Your OpenAI API key.
• AI_CLAUDE_ENABLED: Enable Claude (default: false).
• AI_CLAUDE_API_KEY: Your Claude API key.
• AI_GEMINI_ENABLED: Enable Gemini (default: false).
• AI_GEMINI_API_KEY: Your Gemini API key.

See the Startup Guide for a full list of available environment variables.

The application will be accessible at `http://localhost:9090/atw-rpg`.

Running with a Standalone Tomcat Server

You can also deploy the application to a standalone Tomcat server.

1. Build the .war file:

   ./mvnw clean package -Pproduction,war -DskipTests
   

2. Deploy the .war file:

   You have two options to get the .war file:

   • Build from source: Copy the generated target/all-time-wrestling-rpg-*.war file to the webapps directory of your Tomcat installation.
   • Download from GitHub Releases: Download the latest all-time-wrestling-rpg-*.war from GitHub Releases and copy it to the webapps directory of your Tomcat installation.

   In either case, rename the .war file to atw-rpg.war.

3. Configure Environment Variables:

   Create a setenv.sh (for Linux/macOS) or setenv.bat (for Windows) file to define the required environment variables.

   Important (Homebrew on macOS): To prevent your settings and deployed applications from being overwritten during a brew upgrade, do not use the default Tomcat directories. Instead, create persistent locations and symlink them:

   # 1. Create persistent config and webapps directories
   sudo mkdir -p /opt/homebrew/etc/tomcat/webapps
   
   # 2. Create the setenv.sh file
   cat <<EOF > /opt/homebrew/etc/tomcat/setenv.sh
   

export SPRING_DATASOURCE_URL="jdbc:mysql://localhost:3306/atw" export SPRING_DATASOURCE_USERNAME="root" export SPRING_DATASOURCE_PASSWORD="your_password" export SPRING_FLYWAY_LOCATIONS="classpath:db/migration/mysql" export SPRING_PROFILES_ACTIVE="mysql,prod" export TOMCAT_USERNAME="your_manager_user" export TOMCAT_PASSWORD="your_manager_password" export CATALINA_OPTS="$CATALINA_OPTS -Xms512m -Xmx2g" EOF chmod +x /opt/homebrew/etc/tomcat/setenv.sh

# 3. Create the relink script to handle upgrades automatically
#    It must be idempotent: if you wire it to a launchd WatchPath on
#    /opt/homebrew/opt/tomcat, the path fires on ANY file change in that tree
#    (even transient app temp files), so only restart when a symlink changed.
cat <<EOF > /opt/homebrew/etc/tomcat/relink.sh

#!/bin/bash

Re-establish symlinks after a Homebrew upgrade

setenv_link=/opt/homebrew/opt/tomcat/libexec/bin/setenv.sh webapps_link=/opt/homebrew/opt/tomcat/libexec/webapps changed=0

Symlink setenv.sh

if [ "$(readlink "$setenv_link" 2>/dev/null)" != "/opt/homebrew/etc/tomcat/setenv.sh" ]; then ln -sf /opt/homebrew/etc/tomcat/setenv.sh "$setenv_link" changed=1 fi

Symlink webapps directory

Remove the default webapps directory first if it's not a symlink

if [ ! -L "$webapps_link" ]; then rm -rf "$webapps_link" fi if [ "$(readlink "$webapps_link" 2>/dev/null)" != "/opt/homebrew/etc/tomcat/webapps" ]; then ln -sfn /opt/homebrew/etc/tomcat/webapps "$webapps_link" changed=1 fi

Restart the service only if something actually changed

if [ "$changed" -eq 1 ]; then /opt/homebrew/bin/brew services restart tomcat fi EOF chmod +x /opt/homebrew/etc/tomcat/relink.sh

# 4. Run the relink script for the first time
/opt/homebrew/etc/tomcat/relink.sh
```

**Note (Automating Homebrew Updates):** To automatically re-establish the symlinks and restart Tomcat whenever Homebrew updates the server, you can set up a background LaunchAgent:
```bash
printf '<?xml version="1.0" encoding="UTF-8"?>

launchctl load ~/Library/LaunchAgents/com.atwrpg.relink-tomcat.plist
```

4. Increase Upload Limits and Timeouts (Optional):

By default, Tomcat's Manager application limits uploads to 50 MiB and has a short connection timeout. If your `.war` file exceeds this size (e.g., the 180+ MiB full build), you must increase these limits:

1. Open the Manager app's `web.xml` file:
- **Homebrew**: `/opt/homebrew/opt/tomcat/libexec/webapps/manager/WEB-INF/web.xml`
- **Standard**: `webapps/manager/WEB-INF/web.xml`
2. Locate the `<multipart-config>` section and update the following values (e.g., to 500 MiB):
```xml
<multipart-config>
<!-- 500 MiB max -->
<max-file-size>524288000</max-file-size>
<max-request-size>524288000</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>
```
3. Open the `server.xml` file in your Tomcat `conf` directory and increase the `connectionTimeout` and `maxPostSize` for the HTTP Connector:
```xml
<Connector port="8080" protocol="HTTP/1.1"
		connectionTimeout="300000"
		maxPostSize="524288000"
		maxSwallowSize="524288000"
		redirectPort="8443" />
```
4. Restart Tomcat to apply the changes.

5. Start Tomcat:

Run `startup.sh` or `startup.bat` from the `bin` directory of your Tomcat installation, or use Homebrew:
```bash
brew services restart tomcat
```

If you have set up the Caddy reverse proxy (see [HTTPS over LAN with Caddy](#https-over-lan-with-caddy-qr-code-sharing)), the `relink.sh` script starts Caddy automatically. To start both manually:
```bash
brew services restart tomcat && caddy start --config /opt/homebrew/etc/tomcat/Caddyfile
```

The application will be accessible at http://localhost:8080/atw-rpg (or https://<your-lan-ip>/atw-rpg if Caddy is running).

Configuring Tomcat for HTTPS

The production profile for this application enforces HTTPS. If you are deploying to a standalone Tomcat server, you must configure it to handle HTTPS traffic.

1. Generate a Keystore: A keystore is a file that contains a certificate used by the server to enable HTTPS. For development, you can generate a self-signed certificate.

   Navigate to the conf directory of your Tomcat installation and run the following command:

   keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype JKS -keystore localhost-rsa.jks -validity 36500
   

   You will be prompted for several pieces of information:

   • Password: Enter changeit and confirm it. This password must match the one in the server configuration.
   • First and Last Name: Use localhost. This is the "Common Name" and should match the domain you are using to access the server.
   • Other fields: You can fill these in as you see fit.
   • Confirmation: Type yes to confirm.

   This will create a localhost-rsa.jks file in the conf directory, valid for 100 years.

2. Edit server.xml: Open the server.xml file located in your Tomcat conf directory and ensure the connectors are configured correctly. You need one connector for HTTP that redirects to HTTPS, and another for HTTPS itself.

   Find and replace the existing <Connector> configurations with the following:

   <!-- Define a non-SSL/TLS HTTP/1.1 Connector on port 8080 -->
   <Connector port="8080" protocol="HTTP/1.1"
   		connectionTimeout="20000"
   		redirectPort="8443" />
   
   <!-- Define an SSL/TLS HTTP/1.1 Connector on port 8443 -->
   <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
   		maxThreads="150" SSLEnabled="true">
   	<SSLHostConfig>
   		<Certificate certificateKeystoreFile="conf/localhost-rsa.jks"
   					certificateKeystorePassword="changeit" type="RSA" />
   	</SSLHostConfig>
   </Connector>
   

   This configuration sets up an HTTP listener on port 8080 that automatically redirects to the HTTPS port 8443.

3. Restart Tomcat: After saving the changes to server.xml, restart your Tomcat server.

The application will now be accessible at https://localhost:8443/atw-rpg. Accessing the http://localhost:8080 address will automatically redirect you to the secure HTTPS address.

Note on Browser Warnings: When using a self-signed certificate, your browser will display a security warning. This is expected. You can safely bypass this warning for development by clicking "Advanced" and then "Proceed to localhost (unsafe)". For a public-facing production server, you should obtain a certificate from a trusted Certificate Authority (CA) like Let's Encrypt.

HTTPS over LAN with Caddy (QR Code Sharing)

The Share QR Code feature generates a scannable QR code so players can open a match on their phones. For phones to reach the server, the app must be accessible via a LAN IP address over HTTPS. Caddy handles this with zero certificate management: it terminates HTTPS on port 443, proxies to Tomcat on port 8080, and forwards the real host/protocol via headers so the QR code URL is correct.

Note: Both the server and the scanning device must be on the same Wi-Fi network. Disable any work VPN on the server machine before sharing, as VPN interfaces can interfere with LAN routing.

Prerequisites

• Caddy installed (brew install caddy on macOS)
• Tomcat already running on port 8080

One-time setup

1. Find your LAN IP:

   ipconfig getifaddr en0
   

   Note the IP (e.g. 192.168.4.47).

2. Update the Caddyfile in the project root — replace 192.168.4.47 with your actual LAN IP if it has changed:

   https://192.168.4.47:443 {
   	reverse_proxy localhost:8080 {
   		header_up X-Forwarded-Proto https
   		header_up X-Forwarded-For {remote_host}
   		header_up X-Forwarded-Host {host}
   	}
   }
   

3. Install Caddy's local CA so your Mac trusts the certificate:

   caddy trust
   

4. Trust the cert on each phone (one-time per device):

   Export the CA certificate:

   ls ~/Library/Application\ Support/Caddy/pki/authorities/local/
   # root.crt is in that directory — AirDrop it to the phone
   

   • iOS: Open the file → Install Profile → go to Settings → General → VPN & Device Management and trust it under Certificate Trust Settings.
   • Android: Settings → Security → Install certificate → CA Certificate.

Starting

The Caddyfile is stored at /opt/homebrew/etc/tomcat/Caddyfile alongside the Tomcat config, so it survives upgrades. The relink.sh script starts Caddy automatically when Tomcat is restarted. To start it manually:

caddy start --config /opt/homebrew/etc/tomcat/Caddyfile

The app is then reachable at:

• https://localhost/atw-rpg — from this machine
• https://<your-lan-ip>/atw-rpg — from phones on the same network

Code Quality

Code Coverage

This project maintains a 90% code coverage goal using JaCoCo:

# Run tests with coverage (requires Java 25)
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-25.jdk/Contents/Home mvn clean verify

# View coverage report
open target/site/jacoco/index.html

For detailed coverage guidelines, see CONTRIBUTING.md.

Code Formatting

# Apply code formatting
mvn spotless:apply

Security

This project includes a comprehensive security implementation based on Spring Security to ensure that data is protected and users can only perform actions they are authorized for.

For a detailed guide on account management and user roles, see the User Guide.

For technical details on the security implementation, see the Developer Security Guide.

Maintenance

For details on automated database backups and other maintenance tasks, see the Database Maintenance Guide.

Authentication & Authorization

• Role-Based Access Control: The application uses a robust role-based system with four distinct roles:
• ADMIN: Full system access, including user account management.
• BOOKER: Can manage all game content (shows, wrestlers, etc.).
• PLAYER: Can manage their own wrestler and related items.
• VIEWER: Read-only access to public data.
• Login: Users must authenticate via a login form.
• Default Test Accounts:
• Admin: admin / admin123
• Booker: booker / booker123
• Player: player / player123
• Viewer: viewer / viewer123

⚠️ Important: Change default passwords in a production environment!

Security Features

• Account Lockout: Accounts are automatically locked for 15 minutes after 5 failed login attempts.
• Password Security: Passwords are encrypted using BCrypt (10 rounds).
• Remember Me: Optional 7-day "Remember Me" functionality for trusted devices.
• HTTPS: Enforced in the production environment.

Dependency Security

• OWASP Dependency Check: Automated scanning for vulnerabilities in third-party libraries.
• GitHub Dependency Review: Scans pull requests for dependency vulnerabilities.
• Weekly Security Scans: Automated security scans are run weekly via GitHub Actions.

NVD API Key Configuration

To improve OWASP Dependency Check performance and avoid long update times, configure an NVD API key:

1. Get a free API key: Visit https://nvd.nist.gov/developers/request-an-api-key
2. Set environment variable: export NVD_API_KEY=your-api-key-here
3. Or use Maven property: mvn dependency-check:check -Denv.NVD_API_KEY=your-api-key-here

Without an API key, dependency checks may take significantly longer due to rate limiting.

Security Workflows

This is a public repository with full GitHub Advanced Security features:

• Complete dependency review: License compliance + vulnerability scanning
• GitHub Advanced Security: Full security feature set available
• SARIF integration: Vulnerabilities appear in Security tab
• Automated license compliance: Only approved licenses allowed
• Weekly security scans: Automated vulnerability monitoring

Running Security Scans Locally

# Run OWASP dependency check
mvn org.owasp:dependency-check-maven:check

# Check for dependency updates
mvn versions:display-dependency-updates

# Generate detailed security report
mvn org.owasp:dependency-check-maven:check -Dformats=HTML,JSON,SARIF

Security Policies

• Dependencies with CVSS score ≥ 7.0 will fail the build
• Only approved open source licenses are allowed (enforced on public repos)
• Regular dependency updates are encouraged
• Weekly automated vulnerability scanning

Development Workflow

Pull Request Labeling

This repository uses automated pull request labeling based on changed files:

• Automatic labeling: PRs are automatically labeled based on the files you modify
• Smart categorization: Labels help identify the type and scope of changes
• Review efficiency: Makes it easier for reviewers to understand PR content

Label Categories

• Code Areas: frontend, backend, database, configuration
• Content: documentation, tests, security
• Domain: wrestling, ai, dependencies
• Size: major, minor, patch

Setting Up Labels

Run the label setup script to create all necessary labels:

./scripts/setup-labels.sh