Setup

Deploy guide

Watch the deploy guide

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

0. GitHub access

Create a free GitHub account if you do not have one: https://github.com/signup
Make sure your GitHub account has access to the private playlistcraft-self-host repository.
Accept the collaborator 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

Log in or sign up to Railway with the GitHub option, using the same GitHub account that accepted the collaborator invite.
If you already registered on Railway with email or another method, open Account → Integrations → GitHub and connect that GitHub account.
You do not add playlistcraft-self-host to Railway’s app scope. After the collaborator invite is accepted, One-Click Deploy can access the private template.

2. Open One-Click Deploy

Open the Railway template deploy URL.
Confirm Deploy. Railway opens a new project from the Playlist Craft template.

Deploy creates the project and services. After /setup, paste your activation key into the dashboard’s activate gate.

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.

FAL_KEY="replace_with_fal_key"
OPENROUTER_API_KEY="replace_with_openrouter_api_key"
SUNO_API_KEY="replace_with_suno_api-key"
YOUTUBE_CLIENT_ID="replace_with_client_id"
YOUTUBE_CLIENT_SECRET="replace_with_client_secret"

Resend variables

EMAIL_SERVER="resend"
RESEND_API_KEY="replace_with_resend_api_key"
RESEND_FROM_EMAIL="replace_with_resend_from_email"

ZeptoMail variables

EMAIL_SERVER="zeptomail"
ZEPTOMAIL_TOKEN="replace_with_zeptomail_token"
ZEPTOMAIL_FROM_EMAIL="replace_with_zeptomail_from_email"
ZEPTOMAIL_FROM_NAME="replace_with_zeptomail_from_name"

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 https://sunoapi.org/api-key (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 — create credentials in Google Cloud Console (https://console.cloud.google.com/) and add YOUTUBE_CLIENT_ID + YOUTUBE_CLIENT_SECRET in Shared Variables for YouTube upload (see YouTube OAuth)

Only add the third-party variables listed above. Internal service variables are already generated and cross-referenced by the Railway template.

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

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