Getting Started

Getting Started

This page takes you from a fresh clone to a running hailsDotGO instance on your own machine: install the prerequisites, configure the environment, create the database, run the server, and register your first superadmin account. Once everything works locally, head to Deployment to put it on a server.

Prerequisites

Requirement	Version	Notes
Go	1.25+	go.dev/dl
Node.js + npm	18+	nodejs.org, used only to compile TypeScript with esbuild
MySQL	8+	Stores accounts, shiny collections, and all persistent data
OCR microservice	optional	Powers the IV Calculator screenshot scan; a separate self-hosted Python service (ocr-service/). The rest of the site works without it
OpenSSH client	any	Deployment only, not needed for local development

The Go module builds with CGO_ENABLED=0, so no C toolchain is required. Tesseract is no longer used.

OCR note: Screenshot scanning calls a neural OCR microservice (ocr-service/, RapidOCR) over HTTP at OCR_SERVICE_URL (default http://127.0.0.1:18265/ocr). It is a separate Python service, not part of the Go build, so local development of the main app does not require it; the Screenshot tab simply returns empty fields when the service is unreachable. See Deployment to run it on a server.

Upgrading an existing install? Do not run schema.sql. Use the migrate tool: go run ./cmd/migrate -from <your version> the first time, then go run ./cmd/migrate on every later upgrade. See Database-Guide.

Prefer a tagged release over main if you want a known-good state. main is the active development branch.

1. Clone and install dependencies

git clone https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
make setup        # runs npm install

If you fork the repo or want to track your own changes, also copy the gitignore template so secrets and build output never get committed:

cp .gitignore.example .gitignore

2. Configure the environment

cp .env.example .env

Edit .env and fill in at least DB_HOST, DB_USER, DB_PASS, DB_NAME, and SUPERADMIN_USER. Generate a CSRF key and set it as CSRF_KEY:

openssl rand -hex 32

The app runs without CSRF_KEY, but it then generates a random key on every start, which invalidates CSRF tokens across restarts. Transactional email (signup confirmation, password reset) is optional too: set RESEND_API_KEY and MAIL_FROM to enable it, or leave them unset and those flows quietly skip sending. The full variable reference, including the optional PayPal, transactional email, GitHub sync, and deploy variables, is on the Configuration page.

3. Create the database

schema.sql creates the hailsdotgo database itself (utf8mb4), so you can pipe it straight in:

mysql -u your_db_user -p < schema.sql

Important: schema.sql is the complete current schema for a fresh install, it already reflects every migration, so no extra steps are needed. On an existing install upgrading from an older version, run the numbered sections in migrate.sql that you have not yet applied (each section is clearly labelled). See Database-Guide for the table-by-table breakdown and migration instructions.

The schema seeds the page_*_enabled settings to 1, so all pages are live out of the box. Registration is seeded closed (registration_open = '0').

4. First run

Two processes run side by side during development:

# Terminal 1: recompile TypeScript on save
npm run watch

# Terminal 2: run the Go server
go run .

Or build once and run the binary:

make build   # npm run build + go build -o hailsDotGO .
make run     # ./hailsDotGO

The server reads its configuration from real environment variables. When running locally, export the values from your .env first (for example with set -a; source .env; set +a in bash, or by setting $env:DB_HOST = "..." and friends in PowerShell). The production systemd unit loads them via EnvironmentFile.

Visit http://localhost:8080. On first start the server fetches game data from its upstream sources; if it cannot reach them it falls back to embedded snapshot data, so the site works offline too.

5. Create the first superadmin

Superadmin status is matched by username against the SUPERADMIN_USER environment variable, not by a database role. To bootstrap:

1. Make sure SUPERADMIN_USER in .env is set to the exact username you plan to register.
2. Temporarily open registration:

   UPDATE site_settings SET setting_value = '1' WHERE setting_key = 'registration_open';

3. Start the server and register at /register with that username.
4. Close registration again from the admin panel at /admin (or set the value back to '0' in SQL).

From here you can generate invite codes, toggle pages, and manage users. See Accounts-and-Roles and Admin-Guide.

Platform notes

Windows. Development works natively: npm run watch in one terminal, go run . in another. make is optional (the targets are thin wrappers; run the underlying commands directly if you do not have make). The deploy script deploy.ps1 is PowerShell and expects Windows OpenSSH (ssh, scp, tar are all built in on Windows 10/11).

Linux and macOS. Everything works with the Makefile as written. make dev starts the esbuild watcher in the background and go run . in the foreground; use two terminals if you prefer separate output. make clean removes the binary and the compiled JS bundles.

Next steps

• Configuration for every environment variable
• Database-Guide for schema, migrations, and backups
• Building-and-Development for the build pipeline in depth
• Deployment to put your instance on a Linux server