Configuration

Configuration

hailsDotGO is configured entirely through environment variables. In development you keep them in a local .env file (copied from .env.example); in production the systemd service loads them from /opt/hailsdotgo/app.env, which the deploy script generates for you. This page lists every variable the application and tooling read, with defaults and failure behavior verified against the source.

Quick reference

Variable	Required	Default	Used by	Description
DB_HOST	Yes		app	MySQL host and port, e.g. localhost:3306
DB_USER	Yes		app	MySQL username
DB_PASS	Yes		app	MySQL password
DB_NAME	Yes		app	MySQL database name (schema default: hailsdotgo)
SUPERADMIN_USER	Yes		app	Username with permanent superadmin privileges
CSRF_KEY	Recommended	random per start	app	64 hex chars (32 bytes) for CSRF token signing
PORT	No	8080	app	HTTP listen port
CACHE_DIR	No	cache	app	Disk cache for fetched game data and scraped event pages
LOCALES_DIR	No	locales	app	Approved translation override files and their backups
PAYPAL_CLIENT_ID	Store only		app	PayPal REST API client ID
PAYPAL_CLIENT_SECRET	Store only		app	PayPal REST API client secret
PAYPAL_WEBHOOK_ID	Store only		app	PayPal webhook ID for payment confirmation
PAYPAL_MODE	Store only	sandbox	app	sandbox or live
RESEND_API_KEY	Email only		app	Resend API key for transactional email (signup confirmation, password reset); unset disables all sending
MAIL_FROM	No	hailsDotGO <noreply@hails.cc>	app	From address for transactional email; must use a Resend-verified domain
BASE_URL	No	https://pogo.hails.live	app	Absolute origin used in emailed links (never derived from the request Host header)
GITHUB_TOKEN	Translation sync only		app	Fine-grained PAT for the repo
GITHUB_REPO	Translation sync only		app	Sync target in owner/repo form
VPS_HOST	Deploy only		deploy.ps1	Server hostname or IP, e.g. your.server.com
VPS_USER	Deploy only		deploy.ps1	SSH username on the server
VPS_PASS	No		nothing	Reference only; deploy.ps1 uses key auth, never this
OCR_SERVICE_URL	No	http://127.0.0.1:18265/ocr	app	Endpoint of the OCR microservice for IV Calculator screenshot scanning
RAID_FAST_TIMERS	No	unset	app (dev)	Set to 1 to shrink Raid Finder timers for testing
FCM_PROJECT_ID	Push only		app	Firebase project ID for Android push notifications
FCM_CREDENTIALS_JSON	Push only		app	Path to Firebase service-account credentials JSON
APNS_KEY_PATH	Push only		app	Path to .p8 key file for iOS push notifications
APNS_KEY_ID	Push only		app	10-character APNs key ID from Apple Developer
APNS_TEAM_ID	Push only		app	10-character team ID from Apple Developer
APNS_BUNDLE_ID	Push only		app	App bundle identifier, e.g. live.hails.pogo
APNS_PRODUCTION	No	sandbox	app	Set to "true" for production APNs endpoint

Note: .env.example lists the database, superadmin, CSRF, PayPal, transactional email, VPS, and push notification variables (push entries are commented out). The others (PORT, CACHE_DIR, LOCALES_DIR, BASE_URL, GITHUB_TOKEN, GITHUB_REPO, OCR_SERVICE_URL, RAID_FAST_TIMERS) all have safe defaults and can simply be added to your .env when needed.

Core variables

Database (DB_HOST, DB_USER, DB_PASS, DB_NAME)

Standard MySQL connection settings. DB_HOST takes a host:port address (the driver connects over TCP). The app pings the database at startup and exits if it cannot connect. The connection pool is capped at 10 open and 5 idle connections, and parseTime is enabled. See Database-Guide.

SUPERADMIN_USER

The one variable besides the database settings that the app refuses to start without. It names the account that always has superadmin privileges; the match is by username at request time, not a database column, so set it before registering that account and keep it set. See Accounts-and-Roles.

CSRF_KEY

A 64-character hex string (32 bytes) used to sign CSRF tokens. Generate one with:

openssl rand -hex 32

Behavior (from main.go):

• Unset: the app starts but logs a warning and generates a random key. CSRF tokens then do not survive restarts, which breaks any form open across a restart. Fine for quick local tests, wrong for production.
• Set but malformed (not exactly 64 hex characters): the app exits immediately with the message CSRF_KEY must be a 64-character hex string (32 bytes) and the openssl command to fix it.

PORT

Listen port for the HTTP server, default 8080. In production the app listens on this port on localhost and Caddy terminates HTTPS in front of it; see Deployment.

CACHE_DIR

Directory for the on-disk cache of fetched game data and scraped event pages, default cache under the working directory. Created automatically. The cache is disposable: the app refetches and regenerates everything, and embedded snapshot data covers a cold start with no network. See Operations.

LOCALES_DIR

Directory for approved translation override files, default locales under the working directory. Overrides live outside the binary so they survive redeploys, and every change is backed up to a backup/ subdirectory first. See Localization and Translator-Workspace.

Store variables (optional)

The supporter store is disabled by default. To run it you need a PayPal REST app and all of PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, and PAYPAL_WEBHOOK_ID. PAYPAL_MODE selects the PayPal environment: anything other than live means sandbox. Setup steps are on the Store page.

Transactional email variables (optional)

The app sends signup confirmation and password reset emails through the Resend HTTP API. With RESEND_API_KEY unset the mailer is silently disabled: the flows still render normally, sends are logged and skipped, and nothing else is affected, which is the expected state in local development. MAIL_FROM must use a domain verified in Resend (create the key with sending access only). BASE_URL sets the absolute origin used in the emailed links; it defaults to the production site and is never derived from the request Host header, so a forged Host cannot poison a link.

Push notification variables (optional)

The mobile companion app can send push notifications for raid events (match found, lobby cancelled, 30-second confirm warning). Android uses Firebase Cloud Messaging (FCM); iOS uses Apple Push Notification Service (APNs). Both are silently disabled when their credentials are absent, no errors are logged and no other features are affected.

FCM (Android):

Variable	Description
FCM_PROJECT_ID	Firebase project ID
FCM_CREDENTIALS_JSON	Path to the Firebase service-account credentials JSON file

APNs (iOS):

Variable	Description
APNS_KEY_PATH	Path to the .p8 key file downloaded from Apple Developer
APNS_KEY_ID	10-character key ID from Apple Developer
APNS_TEAM_ID	10-character team ID from Apple Developer
APNS_BUNDLE_ID	App bundle identifier (e.g. live.hails.pogo)
APNS_PRODUCTION	Set to "true" for the production APNs endpoint; omit or leave blank for sandbox/development

OCR microservice (optional)

OCR_SERVICE_URL points the IV Calculator screenshot scanner at the neural OCR microservice (ocr-service/, RapidOCR). It defaults to http://127.0.0.1:18265/ocr, which matches the bundled systemd unit, so you only need to set it if you run the service on a different host or port. When the service is unreachable the Screenshot tab still loads and accepts uploads; it just returns empty extraction fields. Tesseract is no longer used. See Deployment for running the service.

Translation sync variables (optional)

GITHUB_TOKEN and GITHUB_REPO enable the "Sync to GitHub" button in the admin Translations tab, which commits merged locale files to a translations branch and opens a pull request. Use a fine-grained personal access token scoped to that single repository with Contents and Pull requests read/write permissions. GITHUB_REPO is the target in owner/repo form. Without these, manual per-locale export downloads remain available. See Translator-Workspace.

Deploy variables (optional)

VPS_HOST and VPS_USER are read only by the root deploy.ps1 script, never by the app itself. VPS_PASS exists in .env.example purely as a place to note a password for your own reference; the script authenticates exclusively with an SSH key. See Deployment.

Development variables

RAID_FAST_TIMERS=1 shrinks the Raid Finder timers so timeout paths are testable without waiting: the confirm window drops from 2 minutes to 15 seconds, the invite window from 4 minutes to 30 seconds, and the background sweeper runs every 3 seconds instead of every 15. Never set this in production.

About app.env on the server

When you run deploy.ps1, it generates an app.env file from your local .env (database, superadmin, CSRF, PayPal, and GitHub values), uploads it to /opt/hailsdotgo/app.env, sets it to mode 600, and deletes the local copy afterwards. The systemd unit loads it via EnvironmentFile. Both .env and app.env contain secrets and must never be committed; .gitignore.example already excludes them.