v0.1.2a (Deprecated)

Deprecated. This release is superseded by v0.1.2b and is no longer supported. Please upgrade.

---

Beta Warning -- hailsDotGO is in active development. This release is not recommended for production use. APIs, database schema, and configuration may change without notice between versions.

---

What's new in v0.1.2a

• Events page with full details -- current and upcoming Pokemon GO events now display complete details on site (bonuses, featured Pokemon, shinies, raid bosses, research tasks, GO Pass ranks). The server scrapes the matching LeekDuck event page, sanitizes it server side, and caches it to disk, so visitors never need to leave the site
• Shiny Dex -- the shiny gallery is now its own page: every available shiny Pokemon, how to find it, and a normal vs shiny sprite comparison
• Raids moved to pokemon-go-api, plus Max Battles -- live raid bosses (via LeekDuck) and the new Max Battles section (via snacknap) are fetched from pokemon-go-api, cached to disk, and refreshed every 4 hours; the raids page gained tier tabs
• DPS Calculator redesign -- Pokemon are chosen with a sprite search picker (suggestions show sprites, selections show a larger sprite with type badges); the Compare tab target is a single search box listing current raid bosses first with tier tags, with a Custom types toggle; compare results on phones render as ranked attacker cards instead of a sideways-scrolling table
• Public API hardening -- per-IP rate limit of 10 requests per 2 minutes on public endpoints, plus an aggregate bandwidth cap of 15 MB per 5 minutes per IP; the site frontend itself is exempt via the session endpoint /api/app/data
• Admin panel upgrades -- Users tab redesigned as a mini-card grid with a click-to-open modal detail view; account suspension with an optional staff-entered reason shown to the user on login; Custom Tag Requests moved to their own tab with admin revoke
• Custom tag limits -- weekly submission cooldown and a color change rate limit for supporter custom tags
• Automatic asset cache busting -- static asset URLs carry a content hash, so every deploy invalidates browser caches without manual version bumps
• Disk cache -- fetched raid data and scraped event pages persist in a cache directory (configurable via the new optional CACHE_DIR env var, default cache), so the app serves stale data instead of nothing when an upstream fetch fails

---

Prerequisites

Requirement	Version
Go	1.25+
Node.js + npm	18+
MySQL	8+
Caddy (or other reverse proxy)	2+

---

Fresh Install

1. Clone the repo

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

2. Create your .gitignore

This repository no longer ships a .gitignore. If you fork the project or track your own changes, copy the provided template before doing anything else so build output, secrets, and runtime caches never get committed:

cp .gitignore.example .gitignore

This covers the compiled binaries, static/js/ (esbuild output), node_modules/, .env and app.env, the deploy manifest, and the runtime cache/ directory.

3. Install frontend dependencies

npm install

4. Configure environment

cp .env.example .env

Edit .env with your values:

Variable	Required	Description
DB_HOST	Yes	MySQL host and port -- e.g. localhost:3306
DB_USER	Yes	MySQL username
DB_PASS	Yes	MySQL password
DB_NAME	Yes	MySQL database name (e.g. hailsdotgo)
SUPERADMIN_USER	Yes	Username that always has full admin privileges
CSRF_KEY	Recommended	64-char hex string -- generate with openssl rand -hex 32
PORT	No	HTTP listen port, default 8080
CACHE_DIR	No	Directory for fetched game data and scraped event pages, default cache
PAYPAL_CLIENT_ID	Store only	PayPal REST API client ID
PAYPAL_CLIENT_SECRET	Store only	PayPal REST API client secret
PAYPAL_MODE	Store only	sandbox or live
PAYPAL_WEBHOOK_ID	Store only	PayPal webhook ID for payment confirmation

CSRF_KEY is optional but strongly recommended. Without it, CSRF tokens regenerate on every restart and invalidate all active login sessions.

5. Set up the database

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS hailsdotgo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p hailsdotgo < schema.sql

schema.sql creates all tables and seeds the required site_settings rows (all pages default to enabled, registration defaults to closed). The base tables already include every column added by past migrations, so a fresh install needs nothing beyond the file itself.

6. First admin account

Registration is closed on a fresh install. To create your first account:

Option A -- open registration temporarily:

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

Set SUPERADMIN_USER=yourusername in .env, start the server, register at /register, then close registration from the admin panel.

Option B -- promote via SQL after registering:

UPDATE users SET role = 'admin' WHERE username = 'yourusername';

7. Build

# TypeScript (outputs to static/js/)
npm run build

# Go binary (new module dependencies download automatically)
go build -o hailsDotGO .

Or: make build (runs both).

Cross-compile for Linux from Windows:

$env:GOOS = "linux"; $env:GOARCH = "amd64"; $env:CGO_ENABLED = "0"
go build -ldflags="-s -w" -o hailsDotGO-linux .

8. Run locally

# Terminal 1 -- recompile TypeScript on save
npm run watch

# Terminal 2 -- Go server
go run .

Visit http://localhost:8080

---

Server Deployment (Linux / systemd)

Create service user and directory

sudo useradd --system --no-create-home --shell /usr/sbin/nologin hailsdotgo
sudo mkdir -p /opt/hailsdotgo
sudo chown hailsdotgo:hailsdotgo /opt/hailsdotgo

The service user must own /opt/hailsdotgo so the app can create its cache/ directory there at runtime.

Copy files to the server

/opt/hailsdotgo/hailsDotGO     <- compiled Linux/amd64 binary
/opt/hailsdotgo/app.env        <- your .env (chmod 600, owned by hailsdotgo)
/opt/hailsdotgo/templates/     <- all .html files from templates/
/opt/hailsdotgo/static/        <- static/ directory (css, js, sprites)

Install and start the service

A ready-made unit file is included at deploy/hailsdotgo.service. The binary reads configuration from process environment variables only, so make sure the unit's [Service] section points at your env file (add this line if it is not present):

EnvironmentFile=/opt/hailsdotgo/app.env

Then install and start:

sudo cp deploy/hailsdotgo.service /etc/systemd/system/hailsdotgo.service
sudo systemctl daemon-reload
sudo systemctl enable hailsdotgo
sudo systemctl start hailsdotgo

The service runs as the hailsdotgo user and restarts automatically on failure. The server needs outbound HTTPS access to pogoapi.net, the pokemon-go-api and ScrapedDuck GitHub feeds, leekduck.com, and pokeapi.co. No API keys are required for any data source.

---

Reverse Proxy (Caddy)

A sample Caddyfile is included at deploy/Caddyfile. The relevant block:

yourdomain.com {
    encode gzip zstd
    reverse_proxy localhost:8080
}

Replace yourdomain.com with your actual domain. Caddy provisions HTTPS automatically via Let's Encrypt.

sudo systemctl reload caddy

---

Upgrading from v0.1.1a

1. Check out the release

git fetch --tags
git checkout v0.1.2a

2. Create your .gitignore

The tracked .gitignore was removed from the repository in this release and replaced with .gitignore.example, so checking out v0.1.2a deletes the old one from your working tree. Recreate it immediately:

cp .gitignore.example .gitignore

Without this step, git status will start showing binaries, static/js/ output, node_modules/, your .env, and the runtime cache/ directory as untracked files, and they are one careless git add away from being committed.

3. Apply database migrations

Two migration blocks were added to the bottom of schema.sql since v0.1.1a. Run them once against your existing database:

-- Custom tag weekly cooldown + color rate limiting
ALTER TABLE users
  ADD COLUMN tag_requested_at DATETIME NULL AFTER last_seen_at;

CREATE TABLE IF NOT EXISTS tag_color_changes (
  id         INT UNSIGNED NOT NULL AUTO_INCREMENT,
  user_id    INT UNSIGNED NOT NULL,
  changed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_tcc_user_time (user_id, changed_at),
  CONSTRAINT fk_tcc_user FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Account suspension reason
ALTER TABLE users
  ADD COLUMN disabled_reason VARCHAR(255) NOT NULL DEFAULT '' AFTER disabled;

No other schema changes are required. No site_settings rows need to be added.

4. Environment

No new variables are required. One optional variable was added:

Variable	Required	Description
CACHE_DIR	No	Directory for fetched raid data and scraped event pages, default cache (created at runtime in the working directory)

On a systemd deployment the default resolves to /opt/hailsdotgo/cache. Confirm the service user owns /opt/hailsdotgo (it does if you followed the v0.1.1a setup) so the directory can be created.

5. Rebuild

npm install        # no new packages, but safe to re-run
npm run build      # now also bundles the new static/js/shinydex.js
go build -o hailsDotGO .   # new Go modules (goquery, bluemonday) download automatically

6. Redeploy

Upload the new binary plus all changed templates and static files. New files since v0.1.1a that must reach the server:

/opt/hailsdotgo/templates/shinydex.html
/opt/hailsdotgo/static/js/shinydex.js

Nearly every template and bundle changed in this release, so the simplest path is to re-upload templates/ and static/ in full (or run deploy.ps1, which diffs by content hash and uploads only what changed). Then:

sudo systemctl restart hailsdotgo

7. Post-upgrade notes

• Raid data now comes from pokemon-go-api instead of ScrapedDuck; ScrapedDuck is still used for the events feed. Allow outbound HTTPS to both, plus leekduck.com for event detail scraping
• Asset cache busting is automatic; no manual cache clearing is needed after deploys
• Public API consumers now face a 10 requests per 2 minutes rate limit and a 15 MB per 5 minutes bandwidth cap per IP. Logged-in users on the site itself are unaffected

---

Optional: Supporter Store

The store is disabled by default. To enable it:

1. Set the four PAYPAL_* variables in app.env.
2. Enable from the admin panel, or directly:

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

3. Run the store migration block in schema.sql (seeds store_items and purchases tables with two default items).

---

Data Sources

Source	What it provides
PoGoAPI	Pokemon stats, moves, shinies, type effectiveness, CP multipliers
pokemon-go-api	Current raid bosses (via LeekDuck) and Max Battles (via snacknap)
LeekDuck via ScrapedDuck	Events feed, full event details, and event images
PokeAPI	Pokemon sprites, Pokedex text, genus, legendary flags, cries
Open-Meteo	Weather data for GO weather boost detection (no API key required)
Pokemon Showdown	Trainer class sprites for profile avatars
Dreamstone Mysteries	GBA-style trainer sprites (bundled as local static files)