Pull-request previews

Open the previews🔗

Coolify's control plane is at https://alpha2.schmiednet.de. Previews belong to the SongCollect Devs team, project SongCollect, environment pr-previews, and run on the team's server songcollect.schmiednet.de, next to production but with separate resources and volumes.

Previews exist only while their pull request is open, so this guide gives the pattern rather than links to a specific pull request. A wildcard DNS record for *.songcollect.schmiednet.de points to the server, and Traefik's Let's Encrypt resolver supplies certificates per preview host.

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.

Earlier previews ran on beta2 under the Root Team (app 2c0klfivygmeagrwuongwr3w, docs peqcseie9uh7n4q1ze20qy97). Their preview deployments are disabled since the repository moved to the songcollect organization.

Automatic deployment🔗

The team's songcollect-github-app GitHub App deploys the app and docs previews whenever a pull request into main of songcollect/songcollect 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 deploy only production. 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.

Application configuration🔗

Coolify builds the root Dockerfile and serves port 3000. The readiness probe is /api/health/ready. Each preview mounts its own volume xlyyinh3wm0sadm6zxnzuzzr-native-turso-pr-<number> at /data, with TURSO_DATABASE_URL=file:/data/songcollect.db. Uploaded sheet music is stored in /data/assets on the same volume. 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; on songcollect.schmiednet.de that is 172.18.0.2, the coolify-proxy address on the coolify network. Recheck it 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 (songcollect.schmiednet.de, for previews and production) and are not part of any image. Coolify's Docker cleanup runs docker builder prune -af, which removes them. The server 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. Keep other previews and the production volume untouched.