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
OpenSSH client	any	Deployment only, not needed for local development

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

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. The full variable reference, including the optional PayPal, 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 contains the base tables followed by every later migration as commented-out SQL blocks. On a fresh install you must also run each migration block, in order, after the base tables (uncomment them or paste them into the MySQL client). On an existing install you only run the blocks added since your last update. See Database-Guide for the table-by-table breakdown.

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