Set up your own Sona

Fork one repo, run one script, finish in the browser. Expect under an hour from fork to live site. The fastest full launch, domain shopping included, took a single evening.

Never touched a terminal? You’ll be fine. Steps 1–3 are copy-paste (every command is shown below, and the script is safe to re-run), and step 4 happens in your browser.

Prerequisites

  • A GitHub account: your site lives in your fork of the template repo.
  • A Cloudflare account: the free tier is enough. The site runs on Pages, the database on D1, and images in R2, all under your account.
  • Node 20+ and a terminal you don’t mind pasting commands into.
  • Optional but recommended: a domain. Cloudflare gives you a *.pages.dev URL for free if you’d rather start without one.

1 Fork the repo

Fork github.com/sona-fast/sona into your account, then clone your fork:

$ git clone https://github.com/YOUR-USERNAME/sona
$ cd sona
$ npm install

Your fork is your instance. All your configuration stays in Cloudflare, not in the code, so the fork stays clean for syncing updates later.

2 Run the setup script

$ npm run setup

The script asks you to log in to Cloudflare (it opens a browser window), then provisions everything the site needs on your account:

✓ Pages project — serves the site
✓ D1 database — works, artists, credits, settings
✓ R2 bucket — original images and generated variants
✓ deploy secrets written to your GitHub fork
→ SETUP_TOKEN: 7f3a…be21
Keep the SETUP_TOKEN handy. It’s a one-time key that proves you’re the owner when the first-run wizard opens. Once setup is finished the wizard locks, so the token can’t be used by anyone else. If you lose it before finishing, re-run npm run setup to mint a new one.

The script is idempotent: running it again skips anything that already exists.

3 Push to deploy

$ git push origin main

GitHub Actions builds the site, applies database migrations, and deploys to Cloudflare Pages. First deploy takes a couple of minutes; you can watch it in your fork’s Actions tab. When it’s green, your site is live at your-project.pages.dev.

4 First-run wizard

Open /admin/setup on your new site and paste the SETUP_TOKEN. The wizard walks you through, in order:

  • Admin password: you’re the only account; there are no visitor logins. An optional recovery email goes here too.
  • Your site: site name, whose character this is, and a short about text.
  • Social links: optional; they show on your public site.
  • Theme and landing layout: pick a look; you can change any of this later in Settings.

Finish the wizard and you’re looking at your admin panel, ready for your first upload. The shared artist registry isn’t part of setup; you can connect to it from Settings at any time.

How updates work

Updates flow through GitHub’s fork sync. When the upstream repo has new commits, your fork shows a “Sync fork” button. Click it (or git pull upstream main && git push) and the deploy pipeline takes it from there. No reinstalling, no export/import; your content lives in D1 and R2, which updates never touch.

Upstream moves quickly (over a hundred PRs merged in the project’s first two months), so syncing every few weeks is worth the click.

How migrations work

Schema changes ship as numbered migration files. On every deploy, the pipeline checks which migrations your D1 database has already recorded and applies only the new ones, exactly once per instance. Sync a month of updates or a single commit; the result is the same, and re-deploying never re-runs a migration. This is what makes fork sync safe to click without reading the diff.

Issues & contributing

Bug reports and PRs go to the GitHub repo. Questions that aren’t issues: hello@sona.fast or t.me/SonaFastBot.

If you’re wondering what you’d be forking: ~50,000 lines of SvelteKit and TypeScript, 90+ unit test files, a Playwright end-to-end suite, and English + Japanese localization throughout.