Pull-request previews

Open the previews🔗

Coolify's control plane is at https://alpha2.schmiednet.de. The SongCollect project's pr-previews environment deploys its containers to beta2, using the existing alpha2 and beta2 SSH aliases.

Previews exist only while their pull request is open, so this guide gives the pattern rather than links to a specific pull request.

The previous pr-1.songcollect-app.alpha2.schmiednet.de and pr-2.songcollect-docs.alpha2.schmiednet.de URLs redirect to these previews, preserving paths and query strings. The routes are in /data/coolify/proxy/dynamic/songcollect-preview-redirects.yaml on alpha2; Traefik's existing Let's Encrypt resolver supplies HTTPS certificates.

The application account is preview@songcollect.test. Its password is the preview-only PREVIEW_PASSWORD variable in the Coolify app resource. Treat preview data as disposable. Never publish the password or put it in Git.

Automatic deployment🔗

Coolify's coolify-alpha2 GitHub App deploys the app and docs previews whenever a pull request into main is opened, reopened or updated. It only reacts to pull requests whose base branch matches the resource's branch, so both resources track main. Their automatic deployment of pushes is off, so merges to main do not deploy. Pull requests from forks are not deployed. The app posts the preview status as a comment on the pull request; check failures in Coolify.

Redeploy a pull request🔗

Open the resource in Coolify, then Configuration -> Preview Deployments. Select Redeploy for the pull-request number. Check the deployment log, confirm its source commit matches the intended PR head, and open the preview after the deployment finishes. Use the PR deployment controls: the resources' normal branch deployments are not provisioned.

PR #2 targets PR #1's application branch. When updating that base, regenerate the reference and downloadable contract with npm run docs:api:generate, then run npm run docs:api:check and the application checks.

Application configuration🔗

Coolify builds the root Dockerfile and serves port 3000. The readiness probe is /api/health/ready. The current PR #1 container mounts 2c0klfivygmeagrwuongwr3w-native-turso-pr-1 at /data, with TURSO_DATABASE_URL=file:/data/songcollect.db. Keep Coolify's PR volume suffix enabled so separate previews never share storage. No cloud token is required.

Set APP_ORIGIN=$COOLIFY_URL as a non-literal runtime variable in both the normal and preview environments. Coolify expands it to the deployment's exact HTTPS origin. TRUSTED_PROXY_IPS must contain the reverse proxy's exact socket addresses; the current beta2 preview uses 10.0.1.2. Recheck that address when changing networks or hosts.

The image's start command applies checksum-checked migrations before serving. Preview-only runtime variables PREVIEW_BOOTSTRAP=true, PREVIEW_EMAIL, PREVIEW_PASSWORD, and PREVIEW_CHURCH initialize an empty PR installation. Initialization verifies Coolify's PR branch and preserves existing accounts on restart. Updating PREVIEW_PASSWORD does not reset an existing account.

On preview startup, an empty catalogue receives six public-domain hymn records with authors, alternate titles, themes, and copyright metadata. Existing songs are preserved, and sample records do not include lyric text. The sample set is A Mighty Fortress Is Our God, Amazing Grace, Be Thou My Vision, Come, Thou Fount of Every Blessing, Holy, Holy, Holy! Lord God Almighty, and Joy to the World.

Stop the preview before manually changing its schema: native Turso caches schema per process. Use the pinned native SDK and the same image/volume for migration or bootstrap jobs. Do not open the volume with SQLite or libSQL tools. See the repository README for deployment and bootstrap commands.

Documentation configuration🔗

The docs resource uses the Dockerfile build pack with /docs/Dockerfile, built from the repository root, and serves port 80. The image installs Zola 0.23.6 (checksum-pinned), builds the site, and serves docs/public with Nginx using docs/nginx.conf. Its HTTP / health probe checks Nginx. It does not connect to the application database.

The build runs:

zola --root docs build --base-url "${COOLIFY_URL}"

Coolify passes COOLIFY_URL as a build argument. For these resources' Coolify compose parsing version 5 it includes the HTTPS scheme; COOLIFY_FQDN is only the hostname. The base URL must be the preview being built so styles, scripts, navigation, search, and the schema download use it. Do not hard-code a different host. Without the argument, base_url from docs/zola.toml applies.

Verify /, /site.css, /site.js, /search_index.en.json, /api/reference/, and /openapi.json after deploying. Exercise navigation and search in a browser; a successful root health probe alone does not validate generated links.

Build caching🔗

Both Dockerfiles order their steps so that tools and dependencies are installed before the source is copied, and Docker reuses those layers while they are unchanged. The app build also keeps npm downloads and Cargo's registry and compiled dependencies in BuildKit cache mounts (songcollect-* IDs). It recompiles only the songcollect-service package, because Cargo's timestamp checks could otherwise reuse stale output.

These caches live in the Docker daemon of the server that builds the image (beta2) and are not part of any image. Coolify's Docker cleanup runs docker builder prune -af, which removes them. beta2 has Force Docker cleanup disabled, so this only happens when disk usage passes the cleanup threshold (80%), not every night. Do not re-enable it unless disk space requires it: every first build after a cleanup starts cold, which is slower but correct.

Remove a preview🔗

Delete its PR deployment in Coolify when inspection is finished. Remove the PR-specific volume only after its disposable data is no longer needed. Remove obsolete aliases from the alpha2 redirect file when the corresponding preview is retired. Keep other previews and production volumes untouched.