Deploy a Demo App
This guide walks through deploying the Demo App: AI Creator example, which is documented in the Serial Subscriptions integration portal on each project’s dashboard. Treat it as a demonstration: it is not quite ready for full production use, but it shows how your product can integrate with Serial Subscriptions end-to-end and highlights a wide set of platform capabilities, including:
- Tiered subscription plans — multiple plan levels with different entitlements.
- AI token usage — metering and reporting around AI consumption.
- Custom usage tracking — measuring usage by number of ads created (an example of a product-specific metric beyond raw tokens).
- User limits — enforcing caps that align with plan tiers.
For creating a project and enabling your Serial Subscriptions instance, see Create a project.
Open the project dashboard
- Sign in to the integration portal and open the Projects page.
- Select your project’s name or Integrate (or go to the URL
/dashboard/<project-id>for that project).
The dashboard shows your project title, hostname summary, status badges (Status, Domain, Subscription, Domain alias), and an Integrations section.
- Under Integrations, expand Demo App: AI Creator
(A ready-to-deploy example that integrates with Serial Subscriptions.)
The intro text explains that you can start with this demo to explore the full flow, or use Custom App for your own codebase.
What you get
- View on GitHub — Opens the public repository:
https://github.com/serialsubscriptions/ai-creator-demo - Deploy to Vercel — Opens Vercel’s “Deploy” flow with this repository and a suggested set of environment variables. Public values that the portal can derive from your project are prefilled; you still add secrets (database password, API keys, Redis password, client secret) in Vercel.
You can deploy elsewhere (any host that supports Node.js and environment variables). The dashboard instructions assume Vercel for the one-click flow and for hostname setup examples.
Prerequisites
- Active project — Your Serial Subscriptions instance should be provisioned and usable; the dashboard is most helpful when Status is active (or at least past initial errors).
- Subscription — A plan must be attached to the project so the platform can serve your site.
- Domain or alias — For Set SSI_CLIENT_SECRET, Import, Pricing, and Modify Subscription Plans links to work from the dashboard, your project needs a domain alias and/or a custom domain configured. Until then, some buttons stay disabled or links are placeholders; the page explains that links activate once a domain or alias exists.
Environment variables
The demo expects separate public configuration (safe to commit in examples) and private secrets (set only in your host’s secret store).
Public (shown on the dashboard when available)
| Variable | Purpose |
|---|---|
SSI_ISSUER_BASE_URL | Base URL of your Serial Subscriptions site—the issuer used for OAuth/OpenID-style flows. The dashboard sets this to https:// plus your registered domain apex if you configured a custom domain, otherwise the domain alias hostname. |
SSI_COOKIE_DOMAIN | Domain attribute for session cookies. If you use a custom hostname (e.g. account.example.com), this is typically the apex domain (example.com) so cookies work across subdomains. If you only have the platform domain alias, that hostname is used. |
SSI_STORAGE_CONTAINER | Logical container name for storage keys in Redis; the portal sets this from the first segment of your domain alias (e.g. alias myproj.example.platform.tld → container myproj). |
SSI_STORAGE_BACKEND | Must be redis for the demo flow described on the dashboard. |
The dashboard renders copy fields for these when values exist, so you can paste them into Vercel or a local .env file.
Private (secrets — never commit)
| Variable | Purpose |
|---|---|
DATABASE_URL | PostgreSQL connection string for the demo app’s database. |
OPENAI_API_KEY | API key for OpenAI (used by the AI Creator demo). |
SSI_CLIENT_ID | OAuth-style client identifier; the portal aligns this with SSI_STORAGE_CONTAINER for this project. |
SSI_CLIENT_SECRET | Confidential credential for your app when talking to Serial Subscriptions. Not shown on the dashboard. |
SSI_STORAGE_URL | Redis connection URL (e.g. Upstash, Vercel KV, or self-hosted) for session storage and cache invalidation. |
Example shapes (placeholders only):
DATABASE_URL=postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE
OPENAI_API_KEY=sk_YOUR_API_KEY
SSI_STORAGE_URL=redis://:REDIS-PASSWORD@REDIS-HOST:6379/0
SSI_CLIENT_SECRET=AUTH_CLIENT_SECRET
Set SSI_CLIENT_SECRET from the dashboard
Use Set SSI_CLIENT_SECRET on the project dashboard. It opens your Serial Subscriptions site’s auth settings in a new tab:
https://<your-site-host>/settings/auth
Here <your-site-host> is your custom Serial Subscriptions hostname if configured (e.g. account.example.com), otherwise your domain alias. If no host is available yet, the button stays disabled until a domain or alias is assigned.
Create or copy the client secret there, then add the same value as SSI_CLIENT_SECRET in your deployment secrets.
Quick start (in order)
The dashboard Quick start block under the demo app walks through these steps; the list below matches that flow.
1. Connect a database (DATABASE_URL)
Provision PostgreSQL with any provider you prefer (e.g. Vercel Postgres, Neon, Supabase). Add the connection string as DATABASE_URL in your deployment environment.
After the variable is set, run database migrations from the demo application directory. Use the migration command documented in the ai-creator-demo repository (the integration UI notes that exact command may be documented in the repo).
2. Enable Redis for Serial Subscriptions (SSI_STORAGE_URL)
Serial Subscriptions uses Redis for session storage and cache invalidation. Create a Redis instance (e.g. Upstash, Vercel KV, or self-hosted), then set SSI_STORAGE_URL to its connection URL. With SSI_STORAGE_BACKEND=redis, the Serial Subscriptions integration SDK uses Redis for session persistence.
3. Set the hostname for your deployed app
Point your deployment at a hostname under your project so cookies and auth redirects match your Serial Subscriptions configuration.
The dashboard recommends:
app.<your-domain>
- If you have a custom domain on the project (e.g.
example.com), it suggests something likeapp.example.com. - If you only have the domain alias, it suggests
app.<domain-alias>.
Add that hostname in your hosting project (e.g. Vercel Domains) and create DNS at your DNS provider—typically a CNAME from app.yourdomain to your deployment’s target, as described on the dashboard.
If no custom domain is configured yet, the UI directs you to Edit project to add one, then return to the dashboard for updated values.
4. Import the tiered subscription plan template
To load a starter set of subscription plans into your Serial Subscriptions instance:
- On the dashboard, use Copy on the embedded subscription-plan-template.json (a tiered starter template bundled in the integration portal for this step).
Open your site’s Import page (platform admin):
https://<site-admin-host>/admin/config/development/platform-import-export/import<site-admin-host>is your custom domain if set, otherwise your domain alias hostname.Paste the JSON into the import form and run the import.
Review plans on the Pricing page:
https://<site-admin-host>/pricingOr edit them under Modify Subscription Plans:
https://<site-admin-host>/subscription_plan/list
If <site-admin-host> is not available yet, the dashboard shows that these links activate once a domain or domain alias is assigned.
Deploy to Vercel from the dashboard
Deploy to Vercel builds a URL that:
- Clones
https://github.com/serialsubscriptions/ai-creator-demo - Asks for these environment variable names:
DATABASE_URL,OPENAI_API_KEY,SSI_STORAGE_BACKEND,SSI_STORAGE_URL,SSI_COOKIE_DOMAIN,SSI_STORAGE_CONTAINER,SSI_ISSUER_BASE_URL,SSI_CLIENT_ID,SSI_CLIENT_SECRET - Prefills defaults for the public values and placeholders for secrets, using your project’s computed values where possible.
Complete the Vercel wizard: connect your account, confirm the repo, add secret values for database, OpenAI, Redis, and SSI_CLIENT_SECRET, then deploy.
After deployment
- Confirm the app’s URL matches the hostname strategy you configured (
app.<domain>or as allowed by your setup). - Sign in and run through signup/subscription flows against your Serial Subscriptions instance using the issuer and cookie settings from the dashboard.
- Use Edit project or Verify domain on the integration portal if you change domains or DNS.
Custom app instead of the demo
The same dashboard section includes Custom App with overlapping environment variables (without OPENAI_API_KEY), the npx skills add serialsubscriptions/skills scaffold command, and a similar Quick start without the subscription-plan import step. Use that path when integrating Serial Subscriptions into your own codebase rather than deploying the AI Creator demo.
