# 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).