Releases and Upgrading

Releases and Upgrading

This page covers two jobs: standing up a fresh instance from a tagged release (recommended over cloning main), and upgrading an existing install to a newer version. For the first install walkthrough with full detail see Getting Started; for the schema and migration system in depth see Database Guide; for putting an instance on a server see Deployment.

Prefer a tagged release over main for a known-good state. main is the active development branch and is not guaranteed to be stable.

Build from a tagged release

A fresh install from a release tag, rather than tracking main.

Prerequisites

Requirement	Version	Notes
Go	1.25+	go.dev/dl
Node.js + npm	18+	Compiles the 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 service (ocr-service/). See Deployment; the rest of the site works without it

1. Get the code at the tag

git clone https://github.com/Hailey-Ross/hailsDotGO.git
cd hailsDotGO
git checkout v0.1.6a

Alternatively, download the release tarball from the Releases page and extract it.

2. Install dependencies and configure

make setup            # npm install + build the TypeScript bundles
cp .env.example .env

Edit .env and fill in at least DB_HOST, DB_USER, DB_PASS, DB_NAME, and SUPERADMIN_USER. Transactional email is optional: set RESEND_API_KEY and MAIL_FROM to enable signup confirmation and password reset, or leave them unset to skip those sends. The full variable reference is on the Configuration page.

3. Create the schema

mysql -u your_db_user -p your_db_name < schema.sql

schema.sql is the complete current schema and already seeds the full migration history, so a fresh install does not run the migrate tool. (schema.sql also creates the database itself if it does not exist.)

4. Build and run

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

For a development loop, run go run . with npm run watch in a second terminal instead. Then visit http://localhost:8080.

For the first-admin bootstrap and generating a stable CSRF key, follow Getting Started. To put your instance on a server, see Deployment.

Upgrade from a supported release

Moving an existing install up to a newer version.

1. Get the new code and rebuild

git fetch --tags
git checkout v0.1.6a
make build            # rebuilds the TypeScript bundles and the Go binary

2. Run database migrations

Use the migrate tool. It reads migrate.sql, records applied sections in a schema_migrations table, and applies only what is still pending, so it is safe to run repeatedly. Fresh installs created from schema.sql never need it; it is only for upgrades.

First run on an install with no migration history yet. Baseline at your currently installed version (so the tool records everything up to that point as already applied), then apply the rest:

go run ./cmd/migrate -from v0.1.5b   # use YOUR installed version
go run ./cmd/migrate

Every upgrade after the first. The history is already tracked, so just run:

go run ./cmd/migrate

Useful flags:

Flag	Effect
-status	Show applied vs pending sections and exit
-dry-run	Preview what would run without changing anything
-to N	Stop at section N
-baseline current	Record all current sections as applied without running them (for a hand-migrated database)

Supported versions and their migration baseline

Each version maps to the highest migrate.sql section it includes. Use this to pick the -from value that matches your installed version.

Version	Highest applied section
v0.1.1a	22
v0.1.2a	22
v0.1.2b	23
v0.1.2c	25
v0.1.2d	29
v0.1.3a	38
v0.1.4a	41
v0.1.5a	42
v0.1.5b	42
v0.1.6a	43

What v0.1.6a adds

This release adds migration 43, "Regional form support in shiny collection". It adds a region VARCHAR(16) NOT NULL DEFAULT '' column to the user_shinies table (values: empty for the original form, or alolan, galarian, hisuian, paldean). The change is additive with a safe default, so there is no data loss and existing shiny rows keep working as original-form entries.

For the full migration system, section history, and backups, see Database Guide. To redeploy the upgrade to a server, see Deployment.