A static blog commenting system
  • JavaScript 88.8%
  • CSS 10.4%
  • HTML 0.6%
  • Dockerfile 0.2%
Find a file
Matthew Weber aa0650e0d0 Return OAuth users to the blog even from older widget copies
commentario-v2.js (the copy the TLC blog bundles) linked to the OAuth
routes without returnTo, so users always landed on the API root. It now
passes the page URL, and the server falls back to an allowed Referer
when returnTo is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 22:43:57 -05:00
backend Return OAuth users to the blog even from older widget copies 2026-11-20 22:43:57 -05:00
frontend Return OAuth users to the blog even from older widget copies 2026-11-20 22:43:57 -05:00
.env.example Generate the session secret on first start instead of requiring .env 2026-11-06 13:02:44 -05:00
.gitignore multi-site 2026-07-01 19:56:49 -04:00
docker-compose.yml Generate the session secret on first start instead of requiring .env 2026-11-06 13:02:44 -05:00
FRONTEND_UPDATE_GUIDE.md links in admin section 2026-04-03 00:15:57 -04:00
PRE_PUSH_CHECKLIST.md Generate the session secret on first start instead of requiring .env 2026-11-06 13:02:44 -05:00
README.md Generate the session secret on first start instead of requiring .env 2026-11-06 13:02:44 -05:00
SETUP.md Generate the session secret on first start instead of requiring .env 2026-11-06 13:02:44 -05:00
verified.png links in admin section 2026-04-03 00:15:57 -04:00

Commentario

A simple, self-hosted commenting system for static blogs. Perfect for GitLab Pages, GitHub Pages, or any static site generator.

Features

  • Simple & Lightweight: Minimal dependencies, easy to deploy
  • Static Site Friendly: Frontend widget embeds in GitLab Pages (or any static host)
  • Threaded Comments: Full support for nested comment threads with collapsible UI
  • Markdown Support: Full markdown with images and links
  • Anti-Spam: Honeypot field protection + rate limiting
  • Easy Moderation: Web-based moderation panel with password protection
  • Email Notifications: Notify blog owner and commenters of new replies
  • Import Ready: Import existing comments from Hyvor (JSON/XML)
  • Docker Ready: Everything runs in a single container

Architecture

  • Frontend: JavaScript widget (frontend/commentario.js) - host on GitLab Pages
  • Backend: Node.js + Express API server
  • Database: SQLite (file-based, included in container)
  • Deployment: Single Docker container

Quick Start

1. Prerequisites

  • Docker and Docker Compose installed
  • A static blog (Hugo, Jekyll, etc.)
  • GitLab Pages (or similar) for hosting frontend files

2. Setup Backend

# Clone or download this repository
cd Commentario

# Copy environment file
cp .env.example .env

# Edit .env (optional - you can also configure via web UI)
nano .env

The session secret looks after itself: the server generates one on first start and keeps it in data/session-secret beside the database. Set SESSION_SECRET only if you want to supply your own.

Optional: Edit .env and configure:

  • CORS_ORIGIN: Set to your blog's domain (e.g., https://yourusername.gitlab.io)
  • BASE_URL: URL where Commentario will be hosted (e.g., https://comments.yourdomain.com)
  • Email settings (optional but recommended)

Note: Admin password will be set via web UI on first run. You can also pre-configure it in .env if preferred (see Advanced Setup below).

3. Start the Backend & Complete Setup

# Build and start
docker-compose up -d

# Check logs
docker-compose logs -f

Once the backend is running:

  1. Open http://localhost:3000/admin in your browser
  2. You'll see a setup wizard on first run
  3. Create your admin password (minimum 8 characters)
  4. You'll be automatically logged in to the admin panel

That's it! No command-line password generation needed.

4. Deploy Frontend to GitLab Pages

Copy the frontend/ files to your GitLab Pages repository:

# Copy files to your blog's repository
cp frontend/commentario.js your-blog-repo/static/js/
cp frontend/commentario.css your-blog-repo/static/css/

5. Add Widget to Your Blog

Add to your blog template (e.g., layouts/_default/single.html for Hugo):

<!-- In <head> -->
<link rel="stylesheet" href="/css/commentario.css">

<!-- At the end of your post content -->
<div id="commentario"></div>

<script src="/js/commentario.js"></script>
<script>
  new Commentario({
    apiUrl: 'https://your-commentario-backend.com',  // Your backend URL
    pageSlug: '{{ .File.UniqueID }}',  // Unique identifier for this page
    containerId: 'commentario'
  });
</script>

For Hugo specifically:

<script>
  new Commentario({
    apiUrl: 'https://your-backend.com',
    pageSlug: '{{ .File.UniqueID }}',  // or {{ .Permalink }} or {{ .Title | urlize }}
    containerId: 'commentario'
  });
</script>

6. Test It Out

  1. Visit a blog post
  2. Leave a test comment
  3. Check the admin panel at http://localhost:3000/admin
  4. Click "Approve" on the pending comment
  5. Refresh the blog post to see it appear

Advanced Setup

Pre-configure Admin Password (Optional)

If you prefer to set the admin password via environment variable instead of the web UI:

# Generate password hash
docker-compose run --rm commentario node -e "require('bcrypt').hash('your-password', 10).then(console.log)"

# Add to .env
echo "ADMIN_PASSWORD_HASH=paste-hash-here" >> .env

# Restart
docker-compose restart

The setup wizard will be skipped if ADMIN_PASSWORD_HASH is set in .env.

Production Deployment

Deploy Backend to VPS/Cloud

  1. Copy files to your server:

    scp -r Commentario/ user@your-server.com:~/
    
  2. SSH into server and start:

    ssh user@your-server.com
    cd Commentario
    docker-compose up -d
    
  3. Setup reverse proxy (nginx):

    server {
        listen 80;
        server_name comments.yourdomain.com;
    
        location / {
            proxy_pass http://localhost:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
    
  4. Setup SSL with Let's Encrypt:

    sudo certbot --nginx -d comments.yourdomain.com
    

Environment Variables

Variable Required Description
CORS_ORIGIN No Allowed origins for CORS (default: *)
SESSION_SECRET No Signs session cookies. Unset means one is generated and kept in data/session-secret. To supply your own, use a long random string (openssl rand -hex 32); the old example placeholders are refused
ADMIN_PASSWORD_HASH Yes Bcrypt hash of admin password
BASE_URL No Base URL for email links
SMTP_HOST No SMTP server for email notifications
SMTP_PORT No SMTP port (default: 587)
SMTP_USER No SMTP username
SMTP_PASS No SMTP password
SMTP_FROM No From email address
ADMIN_EMAIL No Admin email for notifications

Usage

Moderation

Access the admin panel at /admin:

  1. Pending Comments: Review and approve/spam/delete new comments
  2. Approved Comments: View all approved comments
  3. Spam: View comments marked as spam

All comments are pending by default and must be approved before appearing on your blog.

Importing from Hyvor

  1. Export your Hyvor comments as JSON
  2. Go to /admin/import in your Commentario instance
  3. Paste the JSON data
  4. Click "Import from Hyvor JSON"

Expected JSON format:

{
  "comments": [
    {
      "id": "unique-id",
      "url": "page-slug",
      "author": {
        "name": "Commenter Name",
        "email": "email@example.com",
        "website": "https://example.com"
      },
      "content": "Comment text",
      "date": "2026-01-19T12:00:00Z",
      "status": "approved",
      "parent_id": null
    }
  ]
}

Email Notifications

Configure SMTP settings in .env to enable:

  • Admin notifications: Get notified when new comments are submitted
  • Reply notifications: Commenters get notified when someone replies to their comment

Example Gmail configuration:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password  # Generate at https://myaccount.google.com/apppasswords
SMTP_FROM=your-email@gmail.com
ADMIN_EMAIL=admin@example.com

Anti-Spam Features

  1. Honeypot Field: Hidden field that bots fill out but humans don't see
  2. Rate Limiting: Max 3 comments per minute per IP address
  3. Manual Approval: All comments pending by default
  4. Spam Marking: Mark comments as spam to train yourself to recognize patterns

Password Management

Changing Your Password:

To change your password when logged in:

  1. Go to the admin panel at /admin
  2. Click "Change Password" in the header
  3. Enter your current password
  4. Enter and confirm your new password
  5. Click "Change Password"

Resetting Your Admin Password:

If you forget your admin password, you have two options:

  1. Database reset (easiest):

    # Stop the container
    docker-compose down
    
    # Delete the password from database
    docker-compose run --rm commentario node -e "const db=require('./src/db'); db.prepare('DELETE FROM settings WHERE key=?').run('admin_password_hash');"
    
    # Restart and go through setup wizard again
    docker-compose up -d
    # Visit /admin/setup
    
  2. Set new password via environment variable:

    # Generate new hash
    docker-compose run --rm commentario node -e "require('bcrypt').hash('new-password', 10).then(console.log)"
    
    # Add to .env
    ADMIN_PASSWORD_HASH=paste-hash-here
    
    # Restart
    docker-compose restart
    

API Endpoints

Public Endpoints

  • GET /api/comments/:slug - Get approved comments for a page
  • POST /api/comments/:slug - Submit a new comment

Admin Endpoints (require authentication)

  • GET /admin - Moderation dashboard
  • GET /admin/login - Login page
  • POST /admin/logout - Logout
  • POST /api/admin/approve/:id - Approve a comment
  • POST /api/admin/spam/:id - Mark as spam
  • DELETE /api/admin/delete/:id - Delete a comment
  • GET /admin/import - Import interface
  • POST /api/import/hyvor - Import from Hyvor JSON
  • POST /api/import/wordpress - Import from WordPress JSON

Development

Run Backend Locally

cd backend
npm install
cp .env.example .env
# Edit .env with your settings
npm run dev  # Uses nodemon for auto-restart

Test Frontend Locally

cd frontend
python3 -m http.server 8000
# Open http://localhost:8000/example.html

Make sure the backend is running at http://localhost:3000 or update the apiUrl in example.html.

Tech Stack

  • Backend: Node.js 18, Express 4
  • Database: SQLite (better-sqlite3)
  • Frontend: Vanilla JavaScript (no framework dependencies)
  • Markdown: marked + DOMPurify for safe rendering
  • Email: nodemailer
  • Auth: bcrypt + express-session
  • Container: Docker + Docker Compose

Security

  • Markdown content is sanitized with DOMPurify
  • Honeypot spam protection
  • Rate limiting per IP
  • Password hashing with bcrypt
  • Session-based authentication
  • CORS configuration
  • XSS protection via content sanitization
  • SQL injection protection via parameterized queries

Backup

Database is stored in a Docker volume. To backup:

# Backup
docker-compose exec commentario cat /app/data/commentario.db > backup.db

# Restore
docker cp backup.db commentario:/app/data/commentario.db
docker-compose restart

Troubleshooting

Comments not appearing

  1. Check that CORS is configured correctly in .env
  2. Check browser console for errors
  3. Verify apiUrl matches your backend URL
  4. Check that comments are approved in admin panel

Email not working

  1. Verify SMTP settings in .env
  2. Check Docker logs: docker-compose logs -f
  3. For Gmail, use an App Password, not your regular password
  4. Test with /admin - create a test comment

Docker issues

# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# View logs
docker-compose logs -f

# Check health
docker-compose ps

License

MIT

Contributing

Pull requests welcome! Please ensure:

  • Code follows existing style
  • All features are documented
  • Security best practices are followed

Credits

Built for static site bloggers who want simple, self-hosted comments without the complexity of Disqus or the cost of hosted solutions.