DEPLOY-FREE.md

Deploying Cadence with no credit card

Everything Cadence is is open source. Only the hosting was proprietary, and you don't need to pay for it.

Part	Licence
Flask	BSD-3-Clause
gunicorn	MIT
yt-dlp	Unlicense (public domain)
ytmusicapi	MIT
cloudflared (tunnel)	Apache-2.0
Cadence itself (HTML/CSS/JS/Python)	yours — no dependencies beyond the above, no framework, no build step, no CDN

The three options below all cost 0 € and need no card. Option A is the one I'd pick.

---

Option A — your own machine + a free https tunnel ⭐

Best choice, for a practical reason: the audio is fetched from your internet connection, so YouTube doesn't see a datacenter IP and playback actually works. Cloudflare's tunnel gives you a public https URL with no account, no card, no domain.

# terminal 1 — the backend
cd cadence
./run.sh                       # → http://localhost:8000

# terminal 2 — the https door
bash tunnel.sh                 # installs nothing, prints a URL like:
                               #   https://quite-pets-invalid-renewal.trycloudflare.com

Open that URL on your phone → Install Cadence. Because the backend now serves the app, the manifest, the service worker and the API from that one origin, the installed app works with live search and playback immediately — no backend URL to configure, no CORS, no mixed content.

If cloudflared is missing, bash tunnel.sh downloads it automatically into ./bin (Apache-2.0, ~35 MB, no sudo, no account). The URL appears within ~20 s and the script then verifies it from the public internet. If the tunnel connects but never gets a URL, QUIC is usually blocked on your network — the script retries with --protocol http2 on its own.

No cloudflared at all? bash tunnel.sh --ssh uses localhost.run instead (no download).

One command instead of two

bash tunnel.sh --with-backend

That starts the backend for you (installing dependencies on first run), waits until it answers, opens the tunnel, verifies the public URL and stops the backend again when you press Ctrl+C. Use it when you just want the phone URL without juggling two terminals.

backend not answering on http://127.0.0.1:8000

tunnel.sh needs the backend running in a separate terminal. If it says nothing is listening:

symptom	cause	fix
Permission denied	exec bit lost by zip/checkout	bash run.sh
exits immediately, no message	old run.sh + missing python3-venv	re-download, or sudo apt install python3-venv
ModuleNotFoundError: yt_dlp	dependencies never installed	bash run.sh (installs them)
Address already in use	another program on 8000	PORT=8010 bash run.sh then PORT=8010 bash tunnel.sh
answered once, now dead	terminal closed / laptop slept	start bash run.sh again

run.sh now names the exact cause instead of failing silently, and bash run.sh with Cadence already running just tells you it's up. Check the port yourself any time:

curl -s http://127.0.0.1:8000/healthz     # → {"ok":true,...}

Permission denied on ./tunnel.sh

Zip/checkout tools often drop the executable bit. Any of these works:

bash tunnel.sh          # never needs the exec bit
chmod +x tunnel.sh      # or make it executable once

Things to know

• The URL is temporary: it exists while tunnel.sh runs and changes each restart. Fine for personal use — you just reopen the URL (or reinstall) when it changes.
• It's public: anyone with that URL can use your instance. There is no login. Stop the tunnel when you're done. (A permanent URL needs a free Cloudflare account and a domain — still no card, but no longer zero-setup.)
• Your computer must be awake for the app to work. That's the trade for free + unblocked audio.

Prefer not to use Cloudflare at all? Any tunnel works, e.g. ssh -R 80:localhost:8000 serveo.net or localhost.run — no account either. The app doesn't care.

---

Option B — fully static hosting (free, no backend)

Host only the app. Search and playback are unavailable, but the dashboard, the demo library, charts, genre browsing and offline support all work — and it installs like an app.

Take cadence-android/ and upload it to any of these (none ask for a card):

Host	Free?	Card?	Notes
Codeberg Pages	yes	no	non-profit, open-source-only host — closest to your ask
GitHub Pages	yes	no	push the folder, Settings → Pages → main/root
Cloudflare Pages	yes	no	drag-and-drop a folder
Netlify Drop	yes	no	https://app.netlify.com/drop, no account needed
Any web server you own	yes	no	nginx/Caddy/Apache with https

Codeberg example, entirely with open-source tooling:

cd cadence-android
git init && git add . && git commit -m "Cadence"
git remote add origin https://codeberg.org/<you>/cadence.git
git push -u origin main
# then in the repo: Settings → Pages → branch main → https://<you>.codeberg.page/cadence/

The app starts in demo mode and can later be pointed at an Option A/C URL via the ● demo pill.

---

Option C — a free public backend, no card

If you want a backend that runs without your computer, Hugging Face Spaces is the only widely-used host I know of that runs a Docker service on a free tier with no card:

1. Create a Space at https://huggingface.co/new-space → SDK: Docker → Blank.
2. Upload the contents of cadence/ (or git clone the Space and copy the files in).
3. Add a README.md at the Space root with this front-matter:

---
title: Cadence
sdk: docker
app_port: 7860
pinned: false
---

4. In the Space's Settings → Variables, set PORT=7860 and CADENCE_CACHE=/tmp/cadence.
5. The Space builds and serves at https://<user>-<space>.hf.space — installable PWA included.

Trade-offs, honestly:

• Spaces are public — anyone can visit yours. No auth exists in Cadence.
• The free tier sleeps after inactivity and has limited RAM.
• It runs on datacenter IPs, so YouTube will probably refuse the audio (the youtube_blocked message). Search and browsing work; playback likely won't. That's exactly the problem Option A avoids.
• CADENCE_CACHE must be a writable path (/tmp), and it is not persisted between restarts.

Other free-ish backend hosts (Koyeb, Fly, Railway, Render) now ask for a card for verification — which is what sent you here. If you ever do add a card, DEPLOY.md has those configs ready.

---

Which should you pick?

You want…	Use
App on your Android phone, real playback, zero cost	A — bash run.sh + bash tunnel.sh, install from the https URL
A link you can share that never needs your PC on	B — static demo, installable, free forever
A public backend you can browse from anywhere	C — with the datacenter-audio caveat

Sanity check after any deployment

BASE=https://your-url.example
curl -s $BASE/healthz                      # {"status":"ok",...}
curl -s $BASE/api/stats                    # JSON
curl -s -o /dev/null -w '%{http_code}\n' $BASE/manifest.webmanifest   # 200

Then open $BASE on the phone: the Install Cadence bar should appear. If it doesn't, the page isn't https, or the service worker didn't register (check the browser console).