Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/hostinger-full-stack.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'leroa': patch
---

Add a standalone Hostinger app and PostgreSQL deployment candidate with pinned source builds and explicit validation requirements.
1 change: 1 addition & 0 deletions .github/workflows/ci-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

</div>

Expand Down Expand Up @@ -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). |
Expand Down
46 changes: 46 additions & 0 deletions docker-compose.hostinger.yml
Original file line number Diff line number Diff line change
@@ -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:
78 changes: 67 additions & 11 deletions docs/deploy-hostinger.md
Original file line number Diff line number Diff line change
@@ -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.
82 changes: 82 additions & 0 deletions scripts/test_hostinger.py
Original file line number Diff line number Diff line change
@@ -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()
Loading