Spaces:
Running
Running
| # 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. | |
| ```bash | |
| # 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 | |
| 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: | |
| ```bash | |
| 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 | |
| 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: | |
| ```bash | |
| 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: | |
| ```yaml | |
| --- | |
| 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 | |
| ```bash | |
| 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). | |