Deploy to Vercel

Overview

Vercel provides the ideal hosting platform for the Telegram Subscription Manager with built-in support for Next.js, serverless functions, and cron jobs. This guide walks you through the complete deployment process.

Prerequisites

Before deploying to Vercel, ensure you have:

Completed Database Setup
Completed Telegram Bot Setup
Completed Paystack Configuration
A GitHub account (for connecting your repository)
Your project pushed to a Git repository

Deployment Steps

Push Code to GitHub

Ensure your code is in a Git repository and pushed to GitHub.

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Never commit your .env.local file! Ensure it’s listed in .gitignore to prevent exposing sensitive credentials.

Import Project to Vercel

Go to vercel.com and sign in
Click “Add New Project”
Import your GitHub repository
Select your repository from the list

Vercel will automatically detect that it’s a Next.js project.

Configure Environment Variables

Before deploying, add all required environment variables in the Vercel dashboard:

View All Required Environment Variables

Variable	Description	Example
`TELEGRAM_BOT_TOKEN`	Your bot token from BotFather	`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
`TELEGRAM_CHANNEL_ID`	Your private channel ID	`-1001234567890`
`PAYSTACK_SECRET_KEY`	Paystack secret key	`sk_live_abc123...` or `sk_test_abc123...`
`DATABASE_URL`	MongoDB connection string	`mongodb+srv://user:[email protected]/db`
`CRON_SECRET`	Random secret for cron security	`generate_a_random_secret_here`
`NEXT_PUBLIC_APP_URL`	Your Vercel deployment URL	`https://your-app.vercel.app`

You can add environment variables in the Vercel dashboard under Project Settings → Environment Variables.

Generate a strong CRON_SECRET using: openssl rand -base64 32

Deploy

Click “Deploy” and Vercel will:

Install dependencies (npm install)
Generate Prisma client (prisma generate)
Build your Next.js application
Deploy to a production URL

The build command in package.json automatically runs:

"build": "prisma generate && next build"

Your first deployment will take 2-3 minutes. Subsequent deployments are faster.

Set Telegram Webhook

Once deployed, set your bot’s webhook to point to your Vercel deployment:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-app.vercel.app/api/telegram/webhook"

Replace:

<YOUR_BOT_TOKEN> with your actual bot token
your-app.vercel.app with your Vercel deployment URL

You should see a response:

{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}

Configure Cron Jobs

Create a vercel.json file in your project root to configure the automated expiry check:

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/remove-expired",
      "schedule": "0 * * * *"
    }
  ]
}

This configuration runs the expiry check every hour at minute 0.

Vercel cron jobs use standard cron syntax. The schedule 0 * * * * means “at minute 0 of every hour”.

After adding vercel.json, commit and push:

git add vercel.json
git commit -m "Add cron job configuration"
git push

Vercel will automatically redeploy and configure the cron job.

Verify Deployment

Test your deployment by:

Test the bot: Send /start to your bot on Telegram

Check webhook status:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Verify cron job: Check Vercel dashboard under Deployments → Cron Jobs

Your bot should respond with the welcome message and payment instructions.

Environment Variables Details

Generate CRON_SECRET

The CRON_SECRET protects your cron endpoint from unauthorized access:

# Generate a secure random string
openssl rand -base64 32

Add this value to both:

Your Vercel environment variables
Your local .env.local (for development)

Update NEXT_PUBLIC_APP_URL

After deployment, update NEXT_PUBLIC_APP_URL to your actual Vercel URL:

NEXT_PUBLIC_APP_URL=https://your-app.vercel.app

Don’t forget to update the Telegram webhook URL if you change your Vercel domain!

Cron Job Configuration

The cron job at /api/cron/remove-expired runs every hour to:

Find all expired subscriptions
Remove users from the Telegram channel
Send expiry notifications
Mark subscriptions as removed in the database

Cron Schedule Options

You can adjust the schedule in vercel.json:

Schedule	Runs
`0 * * * *`	Every hour at minute 0
`/30 * * *`	Every 30 minutes
`0 /6 * *`	Every 6 hours
`0 0 * * *`	Daily at midnight

For production, running every hour (0 * * * *) is recommended to ensure timely subscription expiry.

Monitoring and Logs

View Deployment Logs

Go to your Vercel dashboard
Select your project
Click “Deployments”
Click on a deployment to view logs

View Function Logs

For real-time debugging:

Go to Deployments → Functions
Click on a function (e.g., /api/telegram/webhook)
View invocation logs and errors

View Cron Logs

Go to Deployments → Cron Jobs
See execution history and status
Click on an execution to view logs

Vercel automatically retains logs for 7 days on the free tier, 30 days on Pro.

Troubleshooting

Bot Not Responding

Check webhook setup:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Verify:

url matches your Vercel deployment
has_custom_certificate is false
pending_update_count is 0
last_error_date is not present

If webhook is not set:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-app.vercel.app/api/telegram/webhook"

Environment Variables Not Working

Go to Project Settings → Environment Variables
Verify all variables are present
Check for extra spaces or quotes
Ensure variables are set for Production environment
Redeploy after adding/changing variables

Changes to environment variables require a new deployment to take effect!

Cron Job Not Running

Check cron job status:

Go to Vercel dashboard → Deployments → Cron Jobs
Verify the cron job is listed
Check execution history for errors

Common issues:

CRON_SECRET mismatch (must match in environment variables)
Function timeout (increase in Vercel settings)
Database connection errors (check DATABASE_URL)

Test cron endpoint manually:

curl -H "Authorization: Bearer YOUR_CRON_SECRET" \
  https://your-app.vercel.app/api/cron/remove-expired

Build Failures

Check build logs:

Go to Deployments
Click on the failed deployment
View the build logs

Common causes:

Missing DATABASE_URL (Prisma needs it at build time)
TypeScript errors
Missing dependencies

Solution: Ensure DATABASE_URL is set in environment variables before deploying.

Database Connection Errors

If you see “Can’t reach database server” errors:

Verify MongoDB Atlas IP whitelist:
- Go to MongoDB Atlas → Network Access
- Ensure 0.0.0.0/0 is whitelisted (allows Vercel to connect)

Check DATABASE_URL format:

mongodb+srv://username:[email protected]/database?retryWrites=true&w=majority

Test connection locally:
```
npx prisma db push
```

Custom Domain (Optional)

To use a custom domain instead of *.vercel.app:

Add Domain in Vercel

Go to Project Settings → Domains
Enter your custom domain
Follow DNS configuration instructions

Update Environment Variables

Update NEXT_PUBLIC_APP_URL to your custom domain:

NEXT_PUBLIC_APP_URL=https://yourdomain.com

Update Telegram Webhook

Set webhook to your custom domain:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourdomain.com/api/telegram/webhook"

Redeployment

To redeploy your application:

Automatic: Push changes to GitHub
```
git add .
git commit -m "Update feature"
git push
```
Vercel automatically deploys on every push to main branch.
Manual: Trigger deployment in Vercel dashboard
- Go to Deployments
- Click “Redeploy” on any previous deployment

Set up a development branch and configure Vercel to create preview deployments for pull requests!

Get Started

Core Features

Configuration

Deployment

Admin Guide

Overview

Prerequisites

Deployment Steps

Environment Variables Details

Generate CRON_SECRET

Update NEXT_PUBLIC_APP_URL

Cron Job Configuration

Cron Schedule Options

Monitoring and Logs

View Deployment Logs

View Function Logs

View Cron Logs

Troubleshooting

Custom Domain (Optional)

Redeployment

Next Steps

Test Your Bot

Configure Plans

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Admin Guide

​Overview

​Prerequisites

​Deployment Steps

​Environment Variables Details

​Generate CRON_SECRET

​Update NEXT_PUBLIC_APP_URL

​Cron Job Configuration

​Cron Schedule Options

​Monitoring and Logs

​View Deployment Logs

​View Function Logs

​View Cron Logs

​Troubleshooting

​Custom Domain (Optional)

​Redeployment

​Next Steps

Test Your Bot

Configure Plans

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Steps

Environment Variables Details

Generate CRON_SECRET

Update NEXT_PUBLIC_APP_URL

Cron Job Configuration

Cron Schedule Options

Monitoring and Logs

View Deployment Logs

View Function Logs

View Cron Logs

Troubleshooting

Custom Domain (Optional)

Redeployment

Next Steps