Set up publishing
Operator checklist for private source, an authenticated registry and Coolify.
This page is for the instance operator. Team members use the workspace publishing action once setup is complete.
Prerequisites
Before starting, you need:
- A working Wrenly instance with its first owner and one successful saved build.
- Linux with local Docker Engine, Bun, Git,
timeoutandflock. - All checked-in Wrenly migrations applied.
- A Coolify installation and a deployment server it can reach over SSH.
- Free ports for the services below. Coolify's proxy needs its configured HTTP/HTTPS ports.
- Private storage for tokens and an independent backup of your encryption key.
The repository's docker-compose.dev.yml already includes Gitea (port 3030)
and an optional private registry (port 5001). It does not install Coolify.
PostgreSQL in that file stores Wrenly's accounts/projects; the registry stores runnable
images, and Gitea stores generated source. These are three different kinds of storage.
This walkthrough uses one Linux machine for Wrenly, the registry and Coolify's Docker
server. For separate hosts, use an authenticated HTTPS registry reachable from both;
127.0.0.1 always means the machine making the connection.
1. Prepare the runtime
Use Linux with local Docker and the host tools git, timeout and flock. Apply all
checked-in database migrations. Keep publishing disabled until configuration is ready.
For Next.js, make the trusted Bun base image available locally. For Laravel, build the repository-owned toolchain from the repository root:
docker build -t wrenly/laravel-runtime:13-php8.4 packages/sandbox/images/laravel2. Start Gitea and create its token
From the repository root:
docker compose -f docker-compose.dev.yml up -d postgres gitea- Open
http://localhost:3030and create/sign in to your local Gitea account. Keep this installation private while completing its account setup. - Use Gitea's + → New organization to create
wrenly-apps. The account issuing the token must be allowed to create private repositories in this organization. - Open your Gitea profile Settings → Applications → Generate new token.
Give it a recognizable name, such as
wrenly-publishing. Grant repository and organization write access required for private repository creation. Do not restrict it to public repositories. Gitea versions may label these controls differently. - Copy the token once into your private root
.envasWRENLY_GIT_TOKEN. Use the organization name, not its browser URL, forWRENLY_GIT_ORG.
WRENLY_GIT_BASE_URL=http://127.0.0.1:3030
WRENLY_GIT_ORG=wrenly-apps
WRENLY_GIT_TOKEN=PASTE_YOUR_PRIVATE_TOKEN3. Create and start the private registry
Create its ignored password-file directory:
mkdir -p .local/registry/auth
chmod 700 .local .local/registry .local/registry/authCreate a registry password interactively; Docker downloads the utility image if needed:
docker run --rm -it \
--user "$(id -u):$(id -g)" \
--mount "type=bind,source=$(pwd)/.local/registry/auth,target=/auth" \
--entrypoint htpasswd \
httpd:2.4-alpine -Bc /auth/htpasswd wrenly
chmod 600 .local/registry/auth/htpasswdEnter the new password twice and save it privately. wrenly is the registry username;
this password is not your Gitea password. Do not rerun -c against an existing login:
it replaces the password file.
docker compose -f docker-compose.dev.yml --profile publishing up -d
curl -i http://127.0.0.1:5001/v2/
curl -i -u wrenly http://127.0.0.1:5001/v2/The first request should return 401 (authentication required). The second prompts
for your registry password and should return 200. Keep authentication enabled.
The profile binds the registry to loopback and keeps images in wrenly_registry_data.
Do not run down -v: it deletes persistent data.
Add these to the root .env:
WRENLY_REGISTRY_URL=http://127.0.0.1:5001
WRENLY_REGISTRY_NAMESPACE=wrenly
WRENLY_REGISTRY_USERNAME=wrenly
WRENLY_REGISTRY_PASSWORD=PASTE_YOUR_REGISTRY_PASSWORDThe values to collect are:
| Setting | Where its value comes from |
|---|---|
WRENLY_GIT_BASE_URL | Your Gitea service address |
WRENLY_GIT_ORG | The organization created for generated repositories |
WRENLY_GIT_TOKEN | A Gitea token authorized for that organization |
WRENLY_REGISTRY_URL | Your private OCI registry address |
WRENLY_REGISTRY_NAMESPACE | The image namespace used for generated apps |
WRENLY_REGISTRY_USERNAME / WRENLY_REGISTRY_PASSWORD | The registry account used for image pushes |
Remote credential-bearing connections require HTTPS. Local loopback development may
use HTTP. The optional compose publishing profile provides an authenticated registry
on port5001; create its ignored local htpasswd file before starting it. The registry
must not be made public or started without authentication to bypass a setup failure.
4. Install and configure Coolify
If Coolify is not installed, follow its self-hosted installation guide. Complete its initial account/server setup before returning here.
- In Coolify, create a project, for example
wrenly-apps, with aproductionenvironment. - Copy that project's UUID from its settings/address into
WRENLY_COOLIFY_PROJECT_UUID. - Open Servers, select the server that will run generated apps, and copy its UUID
into
WRENLY_COOLIFY_SERVER_UUID. This is not the project's UUID. - Create a Coolify API token authorized to manage applications/deployments on that
target. Save it privately as
WRENLY_COOLIFY_API_KEY. - Use your Coolify address plus
/api/v1asWRENLY_COOLIFY_API_URL. Same-host example:http://127.0.0.1:8000/api/v1. - On the deployment server, as the operating-system user Coolify uses for Docker, run:
docker login 127.0.0.1:5001Enter wrenly and the registry password. This authorizes pulling images. Wrenly's
registry settings authorize pushing them; both are needed. Keep registry credentials
out of the generated app's environment. If Coolify uses another server, loopback will
point at the wrong machine: use your reachable HTTPS registry address instead.
| Setting | Where its value comes from |
|---|---|
WRENLY_COOLIFY_API_URL | Your Coolify API base address, including /api/v1 |
WRENLY_COOLIFY_API_KEY | A scoped API token from your Coolify instance |
WRENLY_COOLIFY_PROJECT_UUID | The target Coolify project's identifier |
WRENLY_COOLIFY_SERVER_UUID | The selected deployment server's identifier |
WRENLY_COOLIFY_ENVIRONMENT | The target environment, such as production |
Configure registry pull credentials on that Coolify server as well. Wrenly's push credentials alone do not authorize another server to pull private images. Confirm that its proxy, DNS and TLS route to the intended application. If another proxy owns ports 80/443, plan routing before starting Coolify's proxy.
5. Protect secrets and enable publishing
Generate a separate encryption key:
openssl rand -hex 32Save it privately as WRENLY_DEPLOY_ENCRYPTION_KEY and back it up separately from
PostgreSQL. Do not reuse the auth secret or overwrite an existing key to rotate it.
Set WRENLY_PUBLISHING_ENABLED=true and restart the API after configuration is complete.
Runtime secrets are delivered separately to Coolify. They do not belong in source, registry image layers or build-time variables. Laravel receives a stable encrypted project key at runtime. A browser runtime-secret editor is not currently available.
6. Verify a real deployment
Publish one small successful revision, open its application URL and verify its behavior. A healthy container alone does not establish routed readiness. Wrenly confirms the remote job, immutable image digest, HTTP response and deployment marker.
Keep the image Coolify needs available. Automatic registry garbage collection and persistent upload/worker management are not implemented. See publishing operations for capacity and recovery.
Coolify succeeded but Wrenly is still checking
A successful Coolify job means its container started. Wrenly then shows Verifying. Wrenly also checks the app's routed URL and a small file identifying this exact deployment. These checks prevent an old app, login screen or unrelated proxy page from being reported as your new app.
- Open the application's Domains/Links in Coolify. Use the application URL, not the Coolify dashboard address ending in port 8000.
- Open that URL in your browser. Then, from the machine running the Wrenly API, run the following with that URL (no provider tokens are needed):
curl --max-time 10 -I 'http://YOUR_APPLICATION_HOST/'
curl --max-time 10 'http://YOUR_APPLICATION_HOST/.well-known/wrenly-deployment'The app should answer successfully and the second request should return the Wrenly deployment UUID. Do not paste a preview hostname or build UUID here.
- If either request fails, check DNS, firewall, the Coolify server's proxy and its
domain route/target port. A generated
sslip.ioname must resolve to a reachable server address. VPNs, DNS rebinding protection and public-IP routing from inside a home network can make browser and API results differ. See Coolify's domain guide. - If the app redirects to a sign-in page, provides only a non-200 root page, or blocks the marker, it does not meet the current readiness profile. Fix the route/app; do not weaken authentication or make the private registry public.
- After a timeout, inspect the exact job in Coolify and follow publishing recovery. Do not repeatedly trigger new deployments while the previous result is uncertain.
Local server cannot reach its own public address
On a home or office network, an app's domain may point to the router's public IP. Some routers cannot send a request from inside the network back through that public address (NAT loopback). The container can be healthy while Wrenly's routed check times out.
For a deployment on the same machine as the API, compare the normal URL with the
local proxy. Replace YOUR_APPLICATION_HOST with the app's hostname from Coolify,
without http://, a path or a port:
curl --max-time 10 'http://YOUR_APPLICATION_HOST/.well-known/wrenly-deployment'
curl --max-time 10 --resolve 'YOUR_APPLICATION_HOST:80:127.0.0.1' \
'http://YOUR_APPLICATION_HOST/.well-known/wrenly-deployment'If only the second works and returns the expected Wrenly deployment UUID, the local proxy/application route works; investigate the public-address/DNS path. Configure your router's loopback or internal DNS. For a local-only same-machine test, an exact host mapping is another option:
sudoedit /etc/hostsAdd a line using the actual hostname:
127.0.0.1 YOUR_APPLICATION_HOSTThen repeat the first curl command without --resolve. Do not map an application to
loopback if it runs on a different server. This mapping affects this machine only; it
does not establish internet reachability. Remove/update the entry when moving to real
public DNS. Do not disable TLS verification or weaken Wrenly's marker check.
Once routing is corrected, follow the interrupted-operation reconciliation steps; refreshing a timed-out attempt does not silently restart publishing.