Deploy Waline Comment System on Vercel

Waline is a simple, safe comment system with Markdown support, email notifications, and multi-language features. This guide walks you through deploying Waline on Vercel using Vercel’s built-in Neon PostgreSQL database, then integrating it with your astro-minimax blog.

Architecture Overview

flowchart TB
    subgraph Blog
        A[astro-minimax Blog] --> B[Waline Client Component]
    end

    subgraph Server
        B --> C[Waline Server
Vercel Deploy]
        C --> D[(Neon PostgreSQL
Vercel Storage)]
        C --> E[Email Service
SMTP / Resend]
        C --> F[Webhook Notification]
    end

    subgraph Channels
        F --> G[Telegram Bot]
        F --> H[Email]
    end

    style A fill:#3b82f6,color:#fff
    style C fill:#22c55e,color:#fff
    style D fill:#00d4aa,color:#fff
    style F fill:#8b5cf6,color:#fff

The system consists of three components:

Prerequisites

Before starting, ensure you have:

• GitHub account (for Vercel login)
• A deployed astro-minimax blog
• Optional: SMTP service or Resend account for email notifications

Step 1: Create Vercel Neon PostgreSQL Database

Vercel provides free Neon PostgreSQL database storage. No need to register for a third-party service - create it with one click.

1.1 Access Vercel Storage

1. Login to Vercel Dashboard
2. Click Storage in the top navigation
3. Click Create Database button

1.2 Create Neon PostgreSQL Database

1. Select Neon PostgreSQL as database type
2. Enter database name, e.g., waline-comments
3. Select region (choose the closest to your users)
4. Click Create to create the database

Neon free tier provides 512MB storage, which is sufficient for personal blog comment systems.

1.3 Initialize Database Schema

Waline requires a specific database schema. After creating the database, import the initialization SQL:

1. On the Vercel Storage page, click the newly created database
2. Click Query tab to enter query interface
3. Copy content from waline.pgsql
4. Paste into query editor and click Run Query

CREATE TABLE IF NOT EXISTS "Comment" (
  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
  "user_id" VARCHAR(255),
  "nick" VARCHAR(255) NOT NULL,
  "mail" VARCHAR(255),
  "link" VARCHAR(255),
  "url" VARCHAR(255),
  "comment" TEXT NOT NULL,
  "ua" VARCHAR(255),
  "ip" VARCHAR(63),
  "is_spam" INTEGER DEFAULT 0,
  "parent" INTEGER,
  "status" VARCHAR(50) DEFAULT 'approved',
  "created_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  "updated_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS "Counter" (
  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
  "url" VARCHAR(255) NOT NULL,
  "time" INTEGER DEFAULT 0
);

CREATE TABLE IF NOT EXISTS "Users" (
  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
  "display_name" VARCHAR(255) NOT NULL,
  "email" VARCHAR(255),
  "url" VARCHAR(255),
  "token" VARCHAR(255),
  "avatar_url" VARCHAR(255),
  "password" VARCHAR(255),
  "label" VARCHAR(255),
  "github_id" VARCHAR(255),
  "twitter_id" VARCHAR(255),
  "facebook_id" VARCHAR(255),
  "google_id" VARCHAR(255),
  "weibo_id" VARCHAR(255),
  "qq_id" VARCHAR(255),
  "recieved" INTEGER DEFAULT 0,
  "created_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  "updated_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX IF NOT EXISTS "idx_comment_url" ON "Comment" ("url");
CREATE INDEX IF NOT EXISTS "idx_comment_user_id" ON "Comment" ("user_id");
CREATE INDEX IF NOT EXISTS "idx_counter_url" ON "Counter" ("url");
CREATE INDEX IF NOT EXISTS "idx_users_email" ON "Users" ("email");

1.4 Get Database Connection Info

On the database details page, click Connect tab to see connection info:

Vercel will automatically inject this information into environment variables. You can also manually copy for backup.

Step 2: Deploy Waline to Vercel

2.1 One-Click Deploy

Click the button below to deploy on Vercel:

Deployment steps:

1. Click the button and login to Vercel with GitHub (if not logged in)
2. Enter project name and click Create to create the project
3. Wait 1-2 minutes until you see the celebration animation indicating successful deployment
4. Click Go to Dashboard to enter project console

2.2 Configure Environment Variables

Add the following environment variables in Vercel project settings:

Tip: If the Waline project and Neon database are under the same Vercel account, you can directly link the database in project settings. Vercel will automatically inject POSTGRES_* environment variables. Waline supports both PG_* and POSTGRES_* prefixes.

Steps in Vercel Dashboard:

1. Project -> Settings -> Environment Variables
2. Add each variable above
3. Click “Save”

2.3 Complete Deployment

1. After configuring environment variables, click “Redeploy”
2. Wait for deployment to complete and get the Vercel assigned domain, e.g., https://your-waline.vercel.app
3. Visit the URL and see the Waline welcome page to confirm successful deployment

2.4 Bind Custom Domain (Optional)

If you have your own domain, you can bind it in Vercel:

1. Project -> Settings -> Domains
2. Enter your domain, e.g., waline.yourdomain.com
3. Add CNAME record in your DNS pointing to cname.vercel-dns.com
4. Wait for DNS to propagate

Step 3: Configure Email Notifications (Optional)

Waline supports multiple email notification methods. Recommended: Resend or SMTP.

Option 1: Resend (Recommended)

Resend provides free email sending service:

1. Register for Resend account
2. Create API Key (format: re_xxx)
3. Verify your sender domain

Add environment variables in Vercel:

Option 2: SMTP

Use Gmail, QQ Mail, or other SMTP services:

Common SMTP service identifiers:

QQ Mail requires an authorization code instead of login password. Get it from QQ Mail Settings -> Account -> POP3/SMTP Service.

Notification Template Configuration

Customize notification email content:

Template variables:

• {{site.name}} - Site name
• {{site.url}} - Site URL
• {{post.title}} - Post title
• {{comment.author}} - Commenter nickname
• {{comment.content}} - Comment content

Step 4: Configure Webhook Notifications

Through Webhook, you can trigger notifications to Telegram or other channels when receiving comments. astro-minimax has a built-in Webhook endpoint.

4.1 Configure Waline Webhook

Add environment variable in Vercel’s Waline project:

4.2 Configure Blog Notifications

Configure notification channels in your blog’s .env file or deployment platform:

# Telegram notification
NOTIFY_TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
NOTIFY_TELEGRAM_CHAT_ID=123456789

# Email notification (optional)
NOTIFY_RESEND_API_KEY=re_xxx
NOTIFY_RESEND_FROM=noreply@yourdomain.com
NOTIFY_RESEND_TO=you@example.com

For complete blog notification configuration, refer to Notification System Configuration Guide.

4.3 Notification Flow

sequenceDiagram
    participant User
    participant Waline
    participant Webhook
    participant Notify
    participant Telegram

    User->>Waline: Post comment
    Waline->>Webhook: POST /api/notify/comment
    Webhook->>Notify: Parse comment data
    Notify->>Telegram: Send notification message
    Telegram-->>User: Receive comment notification

Step 5: Integrate with Blog

Enabling Waline comments in astro-minimax is straightforward.

5.1 Enable Waline Feature

Edit src/config.ts and enable waline in features:

features: {
  tags: true,
  categories: true,
  series: true,
  archives: true,
  friends: true,
  projects: true,
  search: true,
  darkMode: true,
  ai: true,
  waline: true,    // Enable Waline comments
  sponsor: true,
},

5.2 Configure Waline Parameters

Configure the waline object in src/config.ts:

waline: {
  enabled: true,
  serverURL: "https://your-waline.vercel.app/",  // Your Waline server URL
  emoji: [
    "https://unpkg.com/@waline/emojis@1.2.0/weibo",
    "https://unpkg.com/@waline/emojis@1.2.0/bilibili",
    "https://unpkg.com/@waline/emojis@1.2.0/tieba",
  ],
  lang: "en-US",
  pageview: true,
  reaction: true,
  login: "enable",
  wordLimit: [0, 1000],
  imageUploader: false,
  requiredMeta: ["nick", "mail"],
  copyright: true,
  recaptchaV3Key: "",
  turnstileKey: "",
},

5.3 Configuration Parameters

5.4 Login Mode

The login parameter controls comment login behavior:

5.5 CAPTCHA Configuration (Optional)

To prevent spam comments, configure human verification:

Google reCAPTCHA v3:

1. Visit Google reCAPTCHA
2. Create v3 key pair
3. Configure RECAPTCHAV3_SECRET environment variable on server
4. Configure recaptchaV3Key on client

Cloudflare Turnstile:

1. Visit Cloudflare Turnstile
2. Create site key
3. Configure TURNSTILE_SECRET environment variable on server
4. Configure turnstileKey on client

Step 6: Test Comment System

6.1 Local Test

pnpm run dev

Visit any article page and check if the comment section displays correctly.

6.2 Feature Checklist

• Comment section loads correctly
• Can post comments
• Comments display in real-time
• Emojis load correctly
• Email notifications sent (if configured)
• Webhook notifications triggered (if configured)
• Page view statistics display

6.3 Manage Comments

Waline provides an admin dashboard:

1. Visit https://your-waline.vercel.app/ui
2. First visit requires registering an admin account (first registered user becomes admin automatically)
3. You can review, edit, and delete comments in the dashboard

Troubleshooting

Comment Loading Failed

Issue: Comment section shows “Loading failed” or blank.

Troubleshooting:

1. Check if serverURL is correct, ensure it ends with /
2. Check if SECURE_DOMAINS includes your blog URL
3. Open browser developer tools to check network request errors

Comment Submission Failed

Issue: No response or error after posting comment.

Troubleshooting:

1. Check if PostgreSQL environment variables are configured correctly
2. Check if PG_SSL is set to true (required by Neon)
3. Check Vercel logs for error messages
4. Confirm database schema is initialized

Email Notifications Not Sending

Issue: Comments received but no email notification.

Troubleshooting:

1. Check email configuration in Vercel environment variables
2. Check if Resend domain is verified
3. Check email sending errors in Vercel function logs

Webhook Notifications Not Triggering

Issue: Blog notification system not receiving notifications after comments.

Troubleshooting:

1. Confirm WEBHOOK environment variable is configured in Vercel
2. Check blog notification system environment variables
3. Test if Webhook endpoint is accessible:

curl -X POST https://your-blog.pages.dev/api/notify/comment \
  -H "Content-Type: application/json" \
  -d '{"type":"comment","data":{"nick":"test","comment":"test"}}'

PostgreSQL Connection Failed

Issue: Error “Connection refused” or “SSL connection required”.

Solution:

1. Confirm PG_SSL is set to true (Neon requires SSL connection)
2. Check if database host address and port are correct
3. Confirm database is not suspended (Neon free tier suspends after idle, auto-wakes on access)

Neon Database Suspended

Issue: Slow response on first comment.

Solution:

Neon free tier databases auto-suspend after idle and need to wake up on first access. You can:

1. Set up external cron job to periodically ping the database
2. Upgrade to Neon Pro plan for continuous operation

CORS Issues

Issue: Console shows CORS-related errors.

Solution:

1. Configure SECURE_DOMAINS environment variable to add blog domain
2. Ensure Waline server SITE_URL is configured correctly
3. If using custom domain, ensure HTTPS is configured correctly

Advanced Configuration

Multi-language Support

Waline has built-in multi-language support via lang parameter:

lang: "zh-CN",  // Simplified Chinese
lang: "zh-TW",  // Traditional Chinese
lang: "en-US",  // English
lang: "ja-JP",  // Japanese

Custom Styles

Waline supports custom styles via CSS variables. Add to global styles:

:root {
  --waline-font-size: 1rem;
  --waline-theme-color: #3b82f6;
  --waline-active-color: #2563eb;
  --waline-bgcolor: #fff;
  --waline-bgcolor-light: #f8fafc;
}

Image Upload

Enable image upload feature:

imageUploader: true,

Requires configuring storage service on server (e.g., Vercel Blob, S3, etc.).

Sensitive Word Filtering

Configure sensitive word filtering on server:

Other Database Options

Besides Vercel Neon PostgreSQL, Waline supports multiple databases:

For other databases, refer to Waline Documentation.

Next Steps

• Theme Configuration Guide — Learn more configuration options
• Notification System Configuration — Complete notification system setup
• Deployment Guide — Deploy blog to production

By following these steps, you have successfully deployed and integrated the Waline comment system. Waline is feature-rich and easy to deploy, making it an ideal comment solution for personal blogs. If you have questions, visit Waline GitHub Issues for help.