Ship It — Build → Deploy Flow Guide

Step by step

The Full Flow

Follow these five stages every time you ship a new site. No shortcuts — future you will say thanks.

💻

Build locally with opencode DEVELOP

Use opencode as your AI pair-programmer to scaffold and iterate on the site on your machine.

Create a new project folder and open it in your terminal
Run opencode, describe the site, iterate until it works locally
Test it yourself before pushing — broken local code won't fix itself in the cloud

mkdir my-new-site && cd my-new-site
opencode

🐙

Push to GitHub SOURCE OF TRUTH

GitHub is the trigger for everything downstream. Every push to the watched branch tells Coolify "rebuild this".

Create the repo (private is fine — the Coolify GitHub App has access)
Commit and push to main (or your configured deploy branch)

git init
git add .
git commit -m "Initial deploy"
git branch -M main
git remote add origin [email protected]:you/my-new-site.git
git push -u origin main

🚀

Coolify builds it on the VM AUTO-DEPLOY

Our Coolify instance runs on a VM and is connected to GitHub through the Coolify GitHub App. It listens for push events via webhook and rebuilds automatically.

In Coolify: New Project → Application → Private Repository (GitHub App)
Select your repo & branch, pick the build pack (Static / Nixpacks / Dockerfile)
Set the port your app listens on + any environment variables
First deploy is manual — after that, every push auto-deploys ✅

☁️

Expose it with a Cloudflare Tunnel GO PUBLIC

No open ports on the VM. The cloudflared daemon on the VM dials out to Cloudflare, and Cloudflare routes public traffic back down the tunnel to Coolify's app port.

Cloudflare Zero Trust → Networks → Tunnels → pick our tunnel
Add a Public Hostname: mysite.example.com → service http://localhost:PORT (the Coolify app's port)
Cloudflare creates the DNS record automatically

# on the VM, check the tunnel is healthy
systemctl status cloudflared
journalctl -u cloudflared -f

🌐

Verify it's live DON'T SKIP THIS

Open the public URL in an incognito window. Check HTTPS, hard-refresh to bypass cache, and click through the main pages.

✅ Site loads over HTTPS with no warnings
✅ Push a tiny change and confirm it auto-deploys end-to-end
✅ Record the launch in the Deploy Log below

When things break

Troubleshooting

The four ways this flow usually fails, and how to fix each one.

Check the webhook: GitHub repo → Settings → Webhooks → look for failed deliveries (red ❌)
Confirm the Coolify GitHub App still has access to that repo (GitHub → Settings → Applications)
Make sure you pushed to the branch Coolify is watching (usually main)
In Coolify, hit "Redeploy" manually — if that works, it's a webhook issue, not a build issue

Read the deployment log in Coolify — the real error is almost always at the bottom
Wrong build pack? Static sites need "Static", Node apps usually "Nixpacks"
Missing environment variables or a wrong port setting
Does it build locally from a clean clone? If not, fix it locally first

Is cloudflared running on the VM? systemctl status cloudflared
Does the public hostname's service URL match the app's actual port in Coolify? (http://localhost:PORT)
Is the Coolify app actually running (green) — or did the last deploy fail?
Typo in the hostname vs. the DNS record

Check which commit Coolify last deployed — did your push actually trigger a build?
Hard-refresh (Ctrl/Cmd + Shift + R) or test in incognito to bypass cache
Cloudflare caching: purge the cache for that hostname if it's a static asset
Confirm you're looking at the right URL 😅

From opencode to live site
in one flow.