Setup

Deploy guide

This guide walks you from license purchase and GitHub access to a running Playlist Craft dashboard on Railway. The template sources a private GitHub repo — collaborator access is required before Deploy works. License activation unlocks the UI after /setup.

0. GitHub account + purchase email

  1. Create a free GitHub account if you do not have one: https://github.com/signup
  2. Use the same email for GitHub that you will use (or already used) when buying the license on Polar. If your GitHub email differs, contact support after purchase so we can invite the correct account.
  3. Buy on Get license / Pricing. Polar emails your license key and customer portal link.
  4. We invite that email as a collaborator on the private playlistcraft-self-host repository. Accept the invite from GitHub (check inbox / spam).
Without accepting the collaborator invite, Railway shows “Unable to access GitHub repository” on the template deploy page. Repo access and the license key are separate: access lets you deploy; the key unlocks the app.

1. Connect GitHub to Railway

  1. Sign in to Railway (create an account if needed).
  2. Open Account → Integrations → GitHub and connect your GitHub user.
  3. Use Edit scope / configure repository access and include juppfy/playlistcraft-self-host (private). Railway can only clone repos your GitHub user can read and that the GitHub App is allowed to access.

2. Open One-Click Deploy

  1. From playlistcraft.com, click One-Click Deploy (or open the Railway template deploy URL).
  2. Confirm Deploy. Railway opens a new project from the Playlist Craft template.
Deploy creates the project and services. Lifetime product access still needs the license key from Polar pasted into the activate gate after /setup.

3. Project settings → Shared Variables

In the Railway project, open Project Settings → Shared Variables. This is where you configure what you personally must provide. Internal service-to-service API keys are already wired with Railway secret formulas and cross-service references — you should not hand-generate those.

  • Example: s3-server uses a generated PRESIGN_API_KEY (secret formula).
  • main-server references that value from the s3-server service (e.g. S3_SERVER_API_KEY → s3-server.PRESIGN_API_KEY).
  • Similar patterns apply to other internal keys so services trust each other without you pasting matching secrets by hand.

4. What you still fill in (third-party keys)

You only need accounts and API keys from the platforms Playlist Craft calls on your behalf:

  • OpenRouter — ideation / lyrics models (key from https://openrouter.ai/workspaces/default/keys)
  • Suno — music generation via sunoapi.org (credit packs; balances show in the sidebar after generations)
  • Fal — image / video media generation (https://fal.ai/dashboard/keys — use ADMIN scope to show sidebar balances, or API scope to hide them)
  • Email — Resend or ZeptoMail (pick one; see below)
  • Google OAuth — YOUTUBE_CLIENT_ID + YOUTUBE_CLIENT_SECRET in Shared Variables for YouTube upload (see YouTube OAuth)
Never put Polar organization tokens in your Railway project. Polar is only used on playlistcraft.com checkout; activation phones home to Playlist Craft’s license broker. Projected spend: playlistcraft.com/costs.

5. Choose an email provider

Team invites and transactional mail need one provider. Set EMAIL_SERVER to resend or zeptomail and add that provider’s keys to Shared Variables.

Resend (simple free tier)

  • Sign up: https://resend.com/signup
  • Free plan includes about 100 emails per day — enough for admin invites and light transactional use while you get started.
  • Create an API key, verify a sending domain (or use their onboarding sender), set RESEND_API_KEY and RESEND_FROM_EMAIL, and EMAIL_SERVER=resend.

ZeptoMail (credit packs)

  • Sign up: https://www.zoho.com/zeptomail/
  • Credits are purchase-based — roughly $3 can get about 10,000 email credits that expire after 6 months, which is also plenty for self-host usage.
  • Create a token, set ZEPTOMAIL_TOKEN, ZEPTOMAIL_FROM_EMAIL, ZEPTOMAIL_FROM_NAME, and EMAIL_SERVER=zeptomail.
Pick whichever you prefer. You can switch later by changing EMAIL_SERVER and the matching Shared Variables — no code change. Details: Email sender doc.

6. Domains, /setup, activate

  1. Generate public domains for services that need them (especially web, main-server, and youtube-server if used).
  2. Open your web URL → /setup and create the admin account.
  3. Sign in. When the license gate appears, paste the key from Polar.
  4. Start generating. More env/URL detail: Shared variables, Railway services, S3 & public URLs, License activation.