diff --git a/.changeset/hostinger-full-stack.md b/.changeset/hostinger-full-stack.md new file mode 100644 index 0000000..f96dd76 --- /dev/null +++ b/.changeset/hostinger-full-stack.md @@ -0,0 +1,5 @@ +--- +'leroa': patch +--- + +Add a standalone Hostinger app and PostgreSQL deployment candidate with pinned source builds and explicit validation requirements. diff --git a/.github/workflows/ci-release.yml b/.github/workflows/ci-release.yml index 5daf6f3..8fdd5f5 100644 --- a/.github/workflows/ci-release.yml +++ b/.github/workflows/ci-release.yml @@ -115,6 +115,7 @@ jobs: LEROA_DEMO: 'false' run: | npm install -g pnpm@12.4.1 + python3 scripts/test_hostinger.py pnpm install --frozen-lockfile pnpm check pnpm lint diff --git a/README.md b/README.md index 8a56c30..967fdb9 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,9 @@ Leroa is open core: the core is licensed under [MIT](LICENSE-MIT.txt), with sepa [![Deploy on Vercel](https://img.shields.io/badge/Deploy%20on-Vercel-000000?logo=vercel&logoColor=white)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmaxffarrell%2Fleroa&env=DATABASE_URL,BETTER_AUTH_SECRET&envDescription=Postgres%20URL%20and%20a%2032%2B%20char%20random%20secret&stores=%5B%7B%22type%22%3A%22postgres%22%7D%5D) [![Deploy on Render](https://img.shields.io/badge/Deploy%20on-Render-46E3B7?logo=render&logoColor=black)](https://render.com/deploy?repo=https://github.com/maxffarrell/leroa) [![Deploy on DigitalOcean](https://img.shields.io/badge/Deploy%20on-DigitalOcean-0080FF?logo=digitalocean&logoColor=white)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/maxffarrell/leroa/tree/main) +[![Deploy on Hostinger](https://assets.hostinger.com/vps/deploy.svg)](https://www.hostinger.com/docker-hosting?compose_url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaxffarrell%2Fleroa%2Fmain%2Fdocker-compose.hostinger.yml) + +Hostinger: **untested on the provider**. App + PostgreSQL + HTTPS are configured together; requires a Docker VPS, DNS hostname and persistent secrets. [Setup and limitations](docs/deploy-hostinger.md). @@ -53,7 +56,7 @@ Open http://localhost:5173, create an account, then click **Explore with demo da | Render | Button above. `render.yaml` provisions a Docker web service and a Postgres database. | | Koyeb | Manual setup: deploy the `Dockerfile`, add PostgreSQL, and configure `DATABASE_URL` and `BETTER_AUTH_SECRET`. | | DigitalOcean | Button above. `.do/deploy.template.yaml` creates the app and a dev Postgres on App Platform. | -| Hostinger | Manual VPS Docker Manager setup: [deployment guide](docs/deploy-hostinger.md). | +| Hostinger | Button above: app + Postgres + HTTPS on a VPS. **Provider-untested**; [required setup](docs/deploy-hostinger.md). | | Any VPS | [docs/deploy-vps.md](docs/deploy-vps.md) — same compose file on a ~$4 Hetzner VM or Oracle's always-free tier. | | Fly.io | [docs/deploy-fly.md](docs/deploy-fly.md) — `fly launch` using `fly.toml`, scales to zero when idle. | | PikaPods | Not yet in their app catalog — once submitted, a `Run on PikaPods` badge goes here (~$1.50/mo managed). | diff --git a/docker-compose.hostinger.yml b/docker-compose.hostinger.yml new file mode 100644 index 0000000..0d9d3bd --- /dev/null +++ b/docker-compose.hostinger.yml @@ -0,0 +1,46 @@ +# Hostinger VPS deployment candidate. See docs/deploy-hostinger.md for validation status. +# Set POSTGRES_PASSWORD, BETTER_AUTH_SECRET and APP_DOMAIN in the project environment. +services: + proxy: + image: caddy:2-alpine + command: + [ + 'caddy', + 'reverse-proxy', + '--from', + '${APP_DOMAIN:?set the public DNS hostname}', + '--to', + 'app:3000' + ] + ports: ['80:80', '443:443'] + volumes: ['caddy_data:/data', 'caddy_config:/config'] + depends_on: [app] + restart: unless-stopped + app: + # A raw Compose download has no local checkout. Build this reviewed revision. + build: https://github.com/maxffarrell/leroa.git#6cd5d940a43691b38540ea031099927d4aade465 + pull_policy: build + environment: + DATABASE_URL: postgres://leroa:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/leroa + BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET:?set BETTER_AUTH_SECRET} + ORIGIN: https://${APP_DOMAIN:?set the public DNS hostname} + LEROA_ENTERPRISE_KEY: ${LEROA_ENTERPRISE_KEY:-} + depends_on: + db: { condition: service_healthy } + restart: unless-stopped + db: + image: postgres:18-alpine@sha256:b6972e1115a4ff8eba5d7f7d19184926d1e16d7d1136ae1e1a7ebf286da0f015 + environment: + POSTGRES_USER: leroa + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + POSTGRES_DB: leroa + volumes: ['pgdata:/var/lib/postgresql'] + healthcheck: + test: ['CMD-SHELL', 'pg_isready -U leroa'] + interval: 5s + retries: 10 + restart: unless-stopped +volumes: + caddy_data: + caddy_config: + pgdata: diff --git a/docs/deploy-hostinger.md b/docs/deploy-hostinger.md index 33f5a6f..3e6c8ba 100644 --- a/docs/deploy-hostinger.md +++ b/docs/deploy-hostinger.md @@ -1,14 +1,70 @@ -# Deploy on Hostinger +# Deploy on Hostinger VPS -Leroa runs on any Hostinger **VPS** using the Docker Manager (Docker Compose) template. +## Status -1. Create a VPS with the **Docker** OS template (Ubuntu 24.04 with Docker). -2. Open **Docker Manager → Compose → Create project from URL** and paste: - `https://raw.githubusercontent.com/maxffarrell/leroa/main/docker-compose.yml` -3. Set environment variables: - - `BETTER_AUTH_SECRET` – output of `openssl rand -hex 32` - - `POSTGRES_PASSWORD` – a separate output of `openssl rand -hex 32`, kept across upgrades (existing volumes need their existing password) - - `ORIGIN` – your public URL, e.g. `https://pm.example.com` -4. Deploy. Leroa listens on port 3000; point your domain at the VPS and enable HTTPS from **Domains → SSL**. +`docker-compose.hostinger.yml` is a full app-plus-PostgreSQL deployment candidate, +not a verified Hostinger one-click deployment. The README button is provided as +an **untested deployment shortcut**, not a guarantee of a working deployment. +It imports the stack, but users still select/provision a VPS, configure DNS and +set persistent secrets before deploying. +No Hostinger account, purchase, or production deployment was used to validate it. -Upgrades: in Docker Manager choose **Pull & redeploy**. Migrations run automatically on start. +The [documented button](https://www.hostinger.com/support/deploy-on-hostinger-button/) +uses `https://www.hostinger.com/docker-hosting?compose_url=COMPOSE_FILE_URL`, not +`compose=`. The button targets +`https://raw.githubusercontent.com/maxffarrell/leroa/main/docker-compose.hostinger.yml` +on main. When testing unpublished changes, use the raw file URL from the review +branch instead; the button always uses the merged main-branch configuration. +It must be a standalone Compose document. The button may take new customers through Hostinger checkout; VPS +charges depend on the selected plan. + +## What the stack provisions + +- Caddy HTTPS reverse proxy with persistent certificate/configuration volumes. +- The app, built from a pinned, existing repository revision using a remote Git + build context. No local checkout, local `.env` file, or unpublished container + image is assumed. Update the pinned SHA deliberately when upgrading. +- PostgreSQL on the internal Compose network, with a persistent `pgdata` volume + and health check. PostgreSQL has no public port. +- A wired `DATABASE_URL`; the app waits for the database to become healthy. +- The existing Dockerfile startup command runs `node scripts/migrate.ts` before + `node scripts/server.ts`. A failed migration prevents server startup. + +## First deployment + +1. Use a Hostinger VPS with Docker Manager. Import the candidate Compose file + from a published review branch while testing, or main after merge. +2. Configure the project environment before deployment: + - `POSTGRES_PASSWORD`: a persistent, random URL-safe hex password (for example, + `openssl rand -hex 32`). The same value initializes Postgres and the app URL. + - `BETTER_AUTH_SECRET`: a separate random value, at least 32 characters. + - `APP_DOMAIN`: a public DNS hostname (for example `app.example.com`), without + a scheme, port, or path. Its A/AAAA records must point to this VPS. + The app origin is derived as `https://APP_DOMAIN`. +3. Keep these values across redeployments. Changing only the environment does + not rotate the password in an existing PostgreSQL volume. +4. Ensure ports 80 and 443 are available and DNS points to the VPS. The included + Caddy reverse proxy obtains HTTPS certificates automatically and persists them + in named volumes. The app and database have no published host ports. Remove + stale AAAA records if the VPS has no reachable IPv6 address. +5. Deploy the whole project. The app builds from source, then migrates the new DB. + +## Remaining runtime acceptance checks + +Hostinger documents Compose import and environment configuration, and Docker +[documents remote Git build contexts](https://docs.docker.com/reference/compose-file/build/). +Hostinger-specific handling of remote builds and interpolation is not yet tested. + +- Import only this YAML into a fresh project, with no repository checkout or `.env`. +- Verify Hostinger supplies all required variables to Compose interpolation and + builds the pinned Git context. Missing secrets and domain must fail closed. +- Confirm Postgres becomes healthy, migrations finish, and the app serves through + HTTPS. Create a disposable account and exercise a database-backed operation. +- Restart/redeploy the project with the same secrets and verify the account and + data persist. +- Verify port 5432 and the app's port 3000 are not exposed publicly. +- Test a failed migration: the app must not start on an incompatible schema. + +Back up database volumes before upgrades. Never delete them to fix a deployment. +Rebuild after changing the pinned Git revision; pulling images alone does not +update a source-built app. This is VPS self-hosting, not managed PostgreSQL. diff --git a/scripts/test_hostinger.py b/scripts/test_hostinger.py new file mode 100644 index 0000000..c4fa253 --- /dev/null +++ b/scripts/test_hostinger.py @@ -0,0 +1,82 @@ +"""Validate the standalone Hostinger stack without provisioning infrastructure. + +Run: DOCKER_COMPOSE=/path/to/docker-compose python3 scripts/test_hostinger.py +Defaults to `docker compose`. Requires Compose 2.24+; no daemon is needed. +""" +import json +import os +from pathlib import Path +import re +import shlex +import subprocess +import unittest +from urllib.parse import parse_qs, urlsplit + +ROOT = Path(__file__).resolve().parents[1] +APP = json.loads((ROOT / "package.json").read_text())["name"] +COMPOSE = shlex.split(os.environ.get("DOCKER_COMPOSE", "docker compose")) +FIXTURES = { + "APP_DOMAIN": "app.example.test", + "POSTGRES_PASSWORD": "0123456789abcdef0123456789abcdef", + "BETTER_AUTH_SECRET": "abcdef0123456789abcdef0123456789abcdef", +} + + +def config(values): + env = {k: v for k, v in os.environ.items() if k not in FIXTURES} + env.update(values) + return subprocess.run( + COMPOSE + ["--env-file", "/dev/null", "-f", str(ROOT / "docker-compose.hostinger.yml"), "config", "--format", "json"], + env=env, capture_output=True, text=True, + ) + + +class HostingerStack(unittest.TestCase): + def test_button_targets_standalone_stack(self): + readme = (ROOT / "README.md").read_text() + match = re.search(r"\[!\[Deploy on Hostinger\]\([^)]*\)\]\(([^)]+)\)", readme) + self.assertIsNotNone(match) + target = urlsplit(match.group(1)) + self.assertEqual(target.scheme, "https") + self.assertEqual(target.netloc, "www.hostinger.com") + self.assertEqual(target.path, "/docker-hosting") + self.assertEqual(parse_qs(target.query), {"compose_url": [f"https://raw.githubusercontent.com/maxffarrell/{APP}/main/docker-compose.hostinger.yml"]}) + self.assertIn("untested on the provider", readme) + + def test_required_settings_fail_closed(self): + for key in FIXTURES: + with self.subTest(key=key): + result = config({k: v for k, v in FIXTURES.items() if k != key}) + self.assertNotEqual(result.returncode, 0) + self.assertIn(key, result.stderr) + + def test_complete_stack(self): + result = config(FIXTURES) + self.assertEqual(result.returncode, 0, result.stderr) + doc = json.loads(result.stdout) + services = doc["services"] + app, db, proxy = (services[k] for k in ("app", "db", "proxy")) + self.assertEqual(set(services), {"app", "db", "proxy"}) + context = app["build"]["context"] + self.assertRegex(context, rf"^https://github.com/maxffarrell/{APP}\.git#[0-9a-f]{{40}}$") + self.assertNotIn("env_file", app) + self.assertNotIn("ports", app) + self.assertNotIn("ports", db) + self.assertEqual(app["depends_on"]["db"]["condition"], "service_healthy") + self.assertIn("pg_isready", " ".join(db["healthcheck"]["test"])) + self.assertEqual(app["environment"]["DATABASE_URL"], f"postgres://{APP}:{FIXTURES['POSTGRES_PASSWORD']}@db:5432/{APP}") + self.assertEqual(db["environment"]["POSTGRES_PASSWORD"], FIXTURES["POSTGRES_PASSWORD"]) + self.assertEqual(app["environment"]["ORIGIN"], "https://app.example.test") + self.assertEqual(app["environment"]["BETTER_AUTH_SECRET"], FIXTURES["BETTER_AUTH_SECRET"]) + self.assertEqual(proxy["command"], ["caddy", "reverse-proxy", "--from", "app.example.test", "--to", "app:3000"]) + self.assertEqual({p["target"] for p in proxy["ports"]}, {80, 443}) + self.assertTrue({"pgdata", "caddy_data", "caddy_config"}.issubset(doc["volumes"])) + self.assertTrue(any(v["type"] == "volume" and v["target"] == "/var/lib/postgresql" for v in db["volumes"])) + self.assertIn('node scripts/migrate.ts && node scripts/server.ts', (ROOT / "Dockerfile").read_text()) + if APP == "tredaro": + self.assertTrue(any(v["source"] == "uploads" and v["target"] == "/app/data" for v in app["volumes"])) + self.assertIn("chown -R node:node /app/data", (ROOT / "Dockerfile").read_text()) + + +if __name__ == "__main__": + unittest.main()