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.7b

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.7b
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 v0.1.7b (so the tool records everything through section 43 as already applied), then apply the rest:

go run ./cmd/migrate -from v0.1.7b
go run ./cmd/migrate

v0.1.7b is the only baseline the tool now recognises (see the note below). If your install predates v0.1.7b, do a fresh install from schema.sql instead of baselining in place.

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

v0.1.7b is the migration baseline floor. The migrate tool recognises this single version as a -from target; older version strings report unknown version, and migrations run forward from here only.

Version	Highest applied section
v0.1.7b	43

If your install predates v0.1.7b, the supported upgrade path is a fresh install from schema.sql (which seeds the full migration history through section 43), then future upgrades run go run ./cmd/migrate normally. Installs already tracked in schema_migrations are unaffected and need no -from.

What v0.1.7b adds

v0.1.7b is a release milestone rather than a schema change: it bundles the pogo.hails.app move, per-form shiny tracking, the subscribable events calendar, costume label sync, and related work into a tagged, buildable version, and it resets the migration baseline to this release. There is no database change in v0.1.7b; the highest migrate.sql section stays at 43 ("Regional form support in shiny collection", the region column on user_shinies).

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