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

Sign in to Railway (create an account if needed).
Open Account → Integrations → GitHub and connect your GitHub user.
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

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.