Skip to content
Merged
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
45 changes: 32 additions & 13 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ on:
pull_request:
push:
branches: [main]
# "Run workflow" button on the Actions tab: tests, builds and (on main) publishes without a new commit.
workflow_dispatch:

# A newer push to the same pull request cancels the run that is still going.
concurrency:
Expand Down Expand Up @@ -58,21 +60,38 @@ jobs:
cache-from: type=gha
cache-to: type=gha,mode=max

# Deploys main to Fly.io after the tests and the image build passed. Off until the repository
# variable FLY_DEPLOY is "true" and the secret FLY_API_TOKEN is set (README, "Deploying from CI").
deploy:
name: Deploy to Fly.io
# Publishes the image of main to GitHub's container registry, after the tests and the image build
# passed. Every Fly.io instance, the owner's too, deploys that image (fly.toml names it); nothing
# is built on Fly.io, whose builders run out of memory compiling the web app. Forks don't publish.
publish:
name: Publish Docker image
needs: [test, docker]
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.FLY_DEPLOY == 'true'
if: >-
github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
&& github.repository == 'TechbeeAT/GPlayPromoCodeProvider'
runs-on: ubuntu-latest
timeout-minutes: 30
# One deployment at a time, never cancelled halfway.
concurrency:
group: fly-deploy
cancel-in-progress: false
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v5
- uses: superfly/flyctl-actions/setup-flyctl@master
- run: flyctl deploy --remote-only
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
- uses: docker/setup-buildx-action@v3
# The run's own GitHub token may push to the repository's packages: no secret to set up.
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# Same build as the "Build Docker image" job; its cached layers make this quick. Tagged
# "latest" (what fly.toml deploys) and with the commit (to deploy or go back to a fixed version).
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: |
ghcr.io/techbeeat/gplaypromocodeprovider:latest
ghcr.io/techbeeat/gplaypromocodeprovider:${{ github.sha }}
labels: |
org.opencontainers.image.source=https://github.com/TechbeeAT/GPlayPromoCodeProvider
cache-from: type=gha
5 changes: 3 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,9 @@ deciding them.
in `server/.../db/Migrations.kt`, versioned with `PRAGMA user_version`.
- **Docker** image as the single deployable (`Dockerfile`, `docker-entrypoint.sh`), deployed to **Fly.io**
(`fly.toml`, one machine, SQLite file on a Fly volume at `/data`)
- **GitHub Actions** CI (`.github/workflows/ci.yml`): all tests and a Docker build on every PR; optional
deployment of `main` to Fly.io
- **GitHub Actions** CI (`.github/workflows/ci.yml`): all tests and a Docker build on every PR; `main` is
published as `ghcr.io/techbeeat/gplaypromocodeprovider`, which `fly.toml` deploys (CI never deploys;
Fly.io's builders run out of memory on the web app, so nothing is built there)
- UI language: English only (no i18n needed)
- Gradle with Kotlin DSL and a version catalog (`gradle/libs.versions.toml`)
- Package: `at.techbee.gplaypromocodeprovider`
Expand Down
67 changes: 39 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,10 @@ AVAILABLE ──(user requests code)──────▶ CONSUMED
| Database | SQLite (one file, stored on a persistent volume in production). |
| Code upload | Text field, one code per line, multiple codes at once. CSV import may come later. |
| Which code is handed out | The user picks a batch (app, description, expiry date); any available code of that batch is handed out. |
| Deployment | One Docker image (Ktor server also serves the web app), deployable to [Fly.io](https://fly.io). One machine with one volume (SQLite), stopped when idle. Details in [Deployment](#deployment). |
| Deployment | One Docker image (Ktor server also serves the web app), deployable to [Fly.io](https://fly.io). One machine with one volume (SQLite), stopped when idle. The image is built by CI and published on GitHub's container registry; every instance, the owner's included, deploys it the same way with `fly deploy` (Fly.io's builders run out of memory on the web app). Details in [Deployment](#deployment). |
| Web app in production | The Wasm build with the JS build as fallback (Compose's `composeCompatibilityBrowserDistribution`), served by Ktor from `WEB_DIR`: `index.html` for every path that isn't a file, gzip, `Cache-Control: no-cache`. |
| Proxy headers | Ktor trusts `X-Forwarded-*` headers (`XForwardedHeaders`), so it knows the browser used HTTPS behind Fly.io's proxy and sends the `Secure` cookie. A client could fake them when talking to the server directly; nothing relies on the client address, so that's harmless now. A future rate limit per client must use Fly.io's `Fly-Client-IP` instead. |
| CI | GitHub Actions: all tests and a Docker image build on every pull request and push to `main`. Deploying `main` to Fly.io is built in but off until enabled (repository variable `FLY_DEPLOY`). |
| CI | GitHub Actions: all tests and a Docker image build on every pull request and push to `main`; `main` is published as `ghcr.io/techbeeat/gplaypromocodeprovider`. CI doesn't deploy. |
| Language | English only. |
| Build JDK | Java 21, any vendor (Gradle daemon criteria). Not pinned to Azul so cloud AI sessions can use the preinstalled OpenJDK. |
| API models | Separate KMP module `api` (jvm, js, wasmJs), only kotlinx.serialization. The server doesn't pull in Compose. |
Expand Down Expand Up @@ -292,7 +292,7 @@ Fly.io runs Docker images on small virtual machines ("Machines") close to the us
| Setting | Meaning |
|---------|---------|
| `app`, `primary_region` | The app's unique name (address `https://<app>.fly.dev`) and where it runs (`fra`, Frankfurt) |
| `[build]` | Build from the `Dockerfile`; Fly.io builds it on its own builders, no local Docker needed |
| `[build]` | The image to run: `ghcr.io/techbeeat/gplaypromocodeprovider:latest`, published by CI |
| `[env]` | Non-secret environment variables |
| `[mounts]` | The volume `data`, mounted at `/data` |
| `[http_service]` | HTTPS forwarding to port 8080, HTTP redirected to HTTPS, health check on `/api/health`, machine stopped when idle and started on the next request |
Expand All @@ -302,6 +302,13 @@ The app runs on **exactly one machine**: a Fly volume belongs to a single machin
database server several machines could share. Pricing changes; see [fly.io/pricing](https://fly.io/pricing) (a
512 MB machine that is stopped when idle, plus a 1 GB volume, costs a few dollars a month at most).

**Where the image comes from**: it is built by this repository's CI on GitHub and published as
`ghcr.io/techbeeat/gplaypromocodeprovider` (see [CI](#ci)), and `fly.toml` names it (`[build] image`). Fly.io only
downloads and runs it. It doesn't build anything: compiling the web app (Kotlin/JS and Wasm production builds) needs
more memory than Fly.io's remote builders have, and the build gets killed ("Gradle build daemon disappeared
unexpectedly"). So deploying needs no Docker, no Java and no GitHub setup, only `flyctl`, and every instance, the
project owner's included, is set up with the same steps below.

One-time setup:

1. Install [flyctl](https://fly.io/docs/flyctl/install/) and log in (creates an account if needed; Fly.io asks for a
Expand All @@ -311,14 +318,19 @@ One-time setup:
fly auth login
```

2. Pick a unique app name, put it into `fly.toml` (`app = "..."`), and create the app:
2. Get `fly.toml`, the only file the deployment needs: clone this repository (or download just that file) and run
the following commands in its directory.

3. Create the app (or in the Fly.io dashboard), with a name that is free on Fly.io, and put that name into
`fly.toml` (`app = "..."`):

```bash
fly apps create gplay-promo-codes
fly apps create <your-app-name>
```

3. Create the volume for the SQLite file in the same region as in `fly.toml`. 1 GB is plenty (a million codes are a
few dozen MB); it can be extended later with `fly volumes extend`, never shrunk.
4. Create the volume for the SQLite file in the same region as in `fly.toml` (`primary_region`; change both if you
want another region, `fly platform regions` lists them). 1 GB is plenty (a million codes are a few dozen MB); it
can be extended later with `fly volumes extend`, never shrunk.

```bash
fly volumes create data --region fra --size 1
Expand All @@ -327,26 +339,29 @@ One-time setup:
Fly.io warns that a single volume has no redundancy: if the server's disk fails, the data since the last
snapshot is lost. That is accepted here; see [Backups](#backups).

4. Set the admin credentials as **secrets**. Fly.io stores them encrypted and passes them to the server as
5. Set the admin credentials as **secrets**. Fly.io stores them encrypted and passes them to the server as
environment variables; they never appear in `fly.toml` or the repository. Use a long random password.

```bash
fly secrets set ADMIN_USERNAME=admin ADMIN_PASSWORD='<a long random password>'
```

5. Deploy. `--ha=false` makes sure Fly.io creates one machine, not two (its default for high availability):
6. Deploy:

```bash
fly deploy --ha=false
```

Fly.io builds the image, starts a machine with the volume, waits for the health check, and assigns the
addresses. The app is now at `https://<app>.fly.dev`; the admin UI at `https://<app>.fly.dev/admin`.
`--ha=false` makes sure Fly.io creates one machine, not two (its default for high availability). Fly.io downloads
the image, starts a machine with the volume, waits for the health check, and assigns the addresses. The app is
now at `https://<app>.fly.dev`; the admin UI at `https://<app>.fly.dev/admin`.

Updating: run `fly deploy` again (or let CI do it, see [below](#deploying-from-ci)). The machine is replaced by one
with the new image; the volume, and so the data, stays. A deployment logs the admin out (sessions are kept in
memory). Useful commands: `fly status` (machine state), `fly logs` (server output), `fly secrets list` (names only),
`fly ssh console` (a shell in the running machine).
Updating: run `fly deploy` again; it fetches the newest image (`latest`, i.e. the current `main`). To run a fixed
version instead, deploy an image tagged with a commit:
`fly deploy --image ghcr.io/techbeeat/gplaypromocodeprovider:<commit>`.
The machine is replaced by one with the new image; the volume, and so the data, stays. A deployment logs the admin
out (sessions are kept in memory). Useful commands: `fly status` (machine state), `fly logs` (server output),
`fly secrets list` (names only), `fly ssh console` (a shell in the running machine).

**Idle machine**: with `auto_stop_machines = "stop"`, the machine stops after a few minutes without requests and
starts again on the next one, which then takes a few seconds. That also logs the admin out. To keep it running,
Expand Down Expand Up @@ -418,21 +433,17 @@ every pull request and every push to `main`:
with Java 21 and the runner's Chrome. A failing test fails the run; the test reports are then attached to it.
- **Build Docker image**: builds the image (without pushing it), so a broken `Dockerfile` shows up in the pull
request and not only when deploying.
- **Deploy to Fly.io** (optional, off by default): after both jobs passed on `main`, runs `flyctl deploy`.

### Deploying from CI

1. Create a deploy token, which can only deploy this app:

```bash
fly tokens create deploy --expiry 8760h
```
- **Publish Docker image**: after both jobs passed on `main`, builds the image again (from the cached layers, so
quickly) and pushes it to GitHub's container registry as `ghcr.io/techbeeat/gplaypromocodeprovider:latest` and
`...:<commit>`. The run's own GitHub token may do that, so there is no secret to set up. Forks don't publish.
CI never deploys: Fly.io instances fetch the image with `fly deploy` (see [Deploying to Fly.io](#deploying-to-flyio)).

2. In the GitHub repository, under *Settings → Secrets and variables → Actions*: add the token as the **secret**
`FLY_API_TOKEN`, and add the **variable** `FLY_DEPLOY` with the value `true`.
The workflow also has a *Run workflow* button (Actions tab, `workflow_dispatch`): it runs the same jobs for a branch
without a new commit, and publishes when run on `main`.

From then on every merge to `main` is deployed. The token expires after a year (`8760h`); create a new one then.
Remove the variable (or set it to anything else) to stop deploying from CI.
**Package visibility** (once, by the repository owner): the image must be public so that anyone can deploy it. After
the first publish, check on GitHub under the organization's *Packages → gplaypromocodeprovider → Package settings*
that its visibility is *Public*, and change it if not.

---

Expand Down
13 changes: 7 additions & 6 deletions fly.toml
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
# Fly.io configuration, used by `fly deploy`. See README.md ("Deployment") for the step-by-step guide.
# Reference: https://fly.io/docs/reference/configuration/

# The app's name on Fly.io, also its default address: https://<app>.fly.dev. It must be unique on
# Fly.io; change it (or let `fly launch` change it) before the first deployment.
app = "gplay-promo-codes"
# The app's name on Fly.io, also its default address: https://<app>.fly.dev. Names are unique on
# Fly.io: to run your own instance, put the name of the app you created here.
app = "gplaypromocodeprovider"

# Where the machine and its volume run. "fra" is Frankfurt; `fly platform regions` lists the others.
primary_region = "fra"

# Build the image from the Dockerfile in this directory (on Fly.io's builders, so no local Docker is
# needed).
# The image to run: built and published by this repository's CI for every change on main
# (.github/workflows/ci.yml). Fly.io only downloads it and builds nothing; its remote builders run
# out of memory compiling the web app. `fly deploy` fetches the newest "latest" each time.
[build]
dockerfile = "Dockerfile"
image = "ghcr.io/techbeeat/gplaypromocodeprovider:latest"

# Configuration that isn't secret. The Dockerfile already sets PORT, DATABASE_PATH and WEB_DIR;
# ADMIN_USERNAME and ADMIN_PASSWORD are secrets (`fly secrets set`), never in this file.
Expand Down
Loading