- JavaScript 88.8%
- CSS 10.4%
- HTML 0.6%
- Dockerfile 0.2%
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> |
||
|---|---|---|
| backend | ||
| frontend | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| FRONTEND_UPDATE_GUIDE.md | ||
| PRE_PUSH_CHECKLIST.md | ||
| README.md | ||
| SETUP.md | ||
| verified.png | ||
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:
- Open http://localhost:3000/admin in your browser
- You'll see a setup wizard on first run
- Create your admin password (minimum 8 characters)
- 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
- Visit a blog post
- Leave a test comment
- Check the admin panel at http://localhost:3000/admin
- Click "Approve" on the pending comment
- 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
-
Copy files to your server:
scp -r Commentario/ user@your-server.com:~/ -
SSH into server and start:
ssh user@your-server.com cd Commentario docker-compose up -d -
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; } } -
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:
- Pending Comments: Review and approve/spam/delete new comments
- Approved Comments: View all approved comments
- Spam: View comments marked as spam
All comments are pending by default and must be approved before appearing on your blog.
Importing from Hyvor
- Export your Hyvor comments as JSON
- Go to
/admin/importin your Commentario instance - Paste the JSON data
- 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
- Honeypot Field: Hidden field that bots fill out but humans don't see
- Rate Limiting: Max 3 comments per minute per IP address
- Manual Approval: All comments pending by default
- Spam Marking: Mark comments as spam to train yourself to recognize patterns
Password Management
Changing Your Password:
To change your password when logged in:
- Go to the admin panel at
/admin - Click "Change Password" in the header
- Enter your current password
- Enter and confirm your new password
- Click "Change Password"
Resetting Your Admin Password:
If you forget your admin password, you have two options:
-
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 -
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 pagePOST /api/comments/:slug- Submit a new comment
Admin Endpoints (require authentication)
GET /admin- Moderation dashboardGET /admin/login- Login pagePOST /admin/logout- LogoutPOST /api/admin/approve/:id- Approve a commentPOST /api/admin/spam/:id- Mark as spamDELETE /api/admin/delete/:id- Delete a commentGET /admin/import- Import interfacePOST /api/import/hyvor- Import from Hyvor JSONPOST /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
- Check that CORS is configured correctly in
.env - Check browser console for errors
- Verify
apiUrlmatches your backend URL - Check that comments are approved in admin panel
Email not working
- Verify SMTP settings in
.env - Check Docker logs:
docker-compose logs -f - For Gmail, use an App Password, not your regular password
- 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.