Deploying Remark42

Introduction

Remark42 is a self-hosted, privacy-focused comment engine designed for websites and blogs. Written in Go with a React frontend, Remark42 provides a lightweight, fast alternative to third-party commenting services like Disqus without privacy concerns or advertisements.

Built with privacy as a core principle, Remark42 doesn’t track users across sites, doesn’t show ads, and gives you complete control over your comment data. The system supports multiple authentication methods while respecting user privacy.

Key highlights of Remark42:

• Privacy-Focused: No tracking, no ads, no data harvesting
• Multiple Auth Methods: OAuth via Google, GitHub, Facebook, Twitter, and anonymous commenting
• Markdown Support: Rich formatting with Markdown in comments
• Nested Comments: Threaded discussions with unlimited depth
• Voting System: Upvotes and downvotes with customizable scoring
• Real-Time Updates: Live updates when new comments are posted
• Email Notifications: Notify users of replies to their comments
• Telegram Notifications: Admin notifications via Telegram bot
• Multi-Site Support: Host comments for multiple websites
• Import/Export: Migrate from Disqus, WordPress, and other platforms
• Low Resource Usage: Lightweight Go binary with embedded database
• Open Source: Licensed under MIT with active development

This guide walks through deploying Remark42 on Klutch.sh using Docker, configuring authentication providers, and embedding the comment widget on your website.

Why Deploy Remark42 on Klutch.sh

Deploying Remark42 on Klutch.sh provides several advantages for website commenting:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Remark42 without complex orchestration. Push to GitHub, and your comment engine deploys automatically.

Persistent Storage: Attach persistent volumes for your comment database. All discussions and user data survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure OAuth authentication and browser compatibility.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Remark42 is lightweight, but you can scale resources as your comment volume grows.

Environment Variable Management: Securely store OAuth secrets and admin credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Remark42 instance for clean embed URLs.

Always-On Availability: Your comment engine runs 24/7, handling comments for all your sites without downtime.

Prerequisites

Before deploying Remark42 on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Remark42 configuration
• Basic familiarity with Docker and containerization concepts
• OAuth application credentials from at least one provider (Google, GitHub, etc.)
• A website where you’ll embed comments
• (Optional) A custom domain for your Remark42 instance

Understanding Remark42 Architecture

Remark42 is designed for simplicity and performance:

Go Backend: A single Go binary handles all server-side functionality including authentication, comment storage, and API endpoints.

BoltDB Storage: An embedded BoltDB database stores all comments and user data in a single file, eliminating external database dependencies.

React Frontend: The comment widget is a React application that can be embedded on any website.

OAuth Integration: Supports multiple OAuth providers for user authentication without managing passwords.

REST API: Comprehensive API for embedding comments and administrative operations.

Preparing Your Repository

To deploy Remark42 on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

remark42-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM umputun/remark42:latest

# The image is configured via environment variables
# All configuration happens through Klutch.sh env vars

# Create data directory
RUN mkdir -p /srv/var

# Expose the API port
EXPOSE 8080

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Description
REMARK_URL	Yes	External URL of your Remark42 instance
SECRET	Yes	Secret key for JWT tokens
SITE	Yes	Site ID(s) for comments (comma-separated for multiple)
ADMIN_SHARED_ID	No	Shared admin user ID
AUTH_GITHUB_CID	No	GitHub OAuth Client ID
AUTH_GITHUB_CSEC	No	GitHub OAuth Client Secret
AUTH_GOOGLE_CID	No	Google OAuth Client ID
AUTH_GOOGLE_CSEC	No	Google OAuth Client Secret
AUTH_ANON	No	Enable anonymous comments (true/false)
NOTIFY_ADMINS	No	Admin notification method (telegram, email)
NOTIFY_USERS	No	User notification method (email)
SMTP_HOST	No	SMTP server for email notifications
SMTP_PORT	No	SMTP port
SMTP_USERNAME	No	SMTP username
SMTP_PASSWORD	No	SMTP password

Deploying Remark42 on Klutch.sh

Once your repository is prepared, follow these steps to deploy Remark42:

Set Up OAuth Applications

Before deployment, create OAuth applications with your preferred providers.

For GitHub:

1. Go to GitHub Settings → Developer Settings → OAuth Apps
2. Create new OAuth App
3. Set Authorization callback URL to https://your-remark42-domain/auth/github/callback
4. Save Client ID and Client Secret

For Google:

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Create OAuth 2.0 Client ID
3. Add authorized redirect URI: https://your-remark42-domain/auth/google/callback
4. Save Client ID and Client Secret

Generate Secret Key

Generate a secure secret for JWT tokens:

openssl rand -base64 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Remark42 deployment configuration"
git remote add origin https://github.com/yourusername/remark42-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “remark42” or “comments”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Remark42 Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
REMARK_URL	https://your-app-name.klutch.sh
SECRET	Your generated secret key
SITE	your-site-id
AUTH_GITHUB_CID	Your GitHub Client ID
AUTH_GITHUB_CSEC	Your GitHub Client Secret
AUTH_ANON	true (if you want anonymous comments)

Attach Persistent Volumes

Add the following volume for data persistence:

Mount Path	Recommended Size	Purpose
/srv/var	5 GB	Comment database and backups

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Remark42 container
• Provision an HTTPS certificate

Verify Deployment

Access https://your-app-name.klutch.sh/web to see the admin interface and verify the deployment is working.

Embedding Comments on Your Website

Basic Embed Code

Add this code to your website where you want comments to appear:

<div id="remark42"></div>
<script>
  var remark_config = {
    host: 'https://your-remark42-domain.klutch.sh',
    site_id: 'your-site-id',
    components: ['embed'],
    max_shown_comments: 10,
    theme: 'light',
    locale: 'en',
    show_email_subscription: true
  };

  (function(c) {
    for(var i = 0; i < c.length; i++){
      var d = document, s = d.createElement('script');
      s.src = remark_config.host + '/web/' + c[i] + '.js';
      s.defer = true;
      (d.head || d.body).appendChild(s);
    }
  })(remark_config.components || ['embed']);
</script>

Configuration Options

Option	Description
host	URL of your Remark42 instance
site_id	Unique identifier for your site
max_shown_comments	Initial number of comments to display
theme	Color theme (light, dark)
locale	Language code (en, de, ru, etc.)
show_email_subscription	Show email subscription option
page_title	Override page title for comments

Counter Widget

Display comment counts on listing pages:

<span class="remark42__counter" data-url="PAGE_URL"></span>
<script>
  var remark_config = {
    host: 'https://your-remark42-domain.klutch.sh',
    site_id: 'your-site-id',
    components: ['counter']
  };
</script>

Production Best Practices

Security Recommendations

• Secure Secret Key: Use a strong, unique secret and never commit it to version control
• OAuth Security: Keep OAuth credentials secure
• CORS Configuration: Configure allowed origins for your websites
• Admin Access: Protect admin endpoints appropriately

Performance Optimization

• CDN for Widget: Consider serving the JavaScript widget from a CDN
• Caching: Enable browser caching for static assets
• Database Maintenance: BoltDB requires minimal maintenance

Backup Strategy

1. Database Backup: Back up /srv/var containing the BoltDB database
2. Export Comments: Use the admin interface to export comments as JSON
3. Configuration Backup: Document all environment variables

Troubleshooting Common Issues

OAuth Not Working

Symptoms: Users can’t log in via OAuth providers.

Solutions:

• Verify callback URLs match exactly
• Check OAuth credentials are correct
• Ensure REMARK_URL matches your actual URL
• Review logs for OAuth errors

Comments Not Appearing

Symptoms: Widget loads but no comments show.

Solutions:

• Verify site_id matches configuration
• Check browser console for JavaScript errors
• Ensure host URL is correct
• Verify CORS allows your website

Widget Not Loading

Symptoms: Comment widget doesn’t appear on page.

Solutions:

• Check script URL is accessible
• Verify no JavaScript errors in console
• Ensure div with id=“remark42” exists
• Check for ad-blocker interference

Additional Resources

• Official Remark42 Website
• Remark42 GitHub Repository
• Remark42 Documentation
• Frontend Configuration
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Remark42 on Klutch.sh gives you a privacy-focused, self-hosted comment system with automatic builds, persistent storage, and secure HTTPS access. The combination of Remark42’s lightweight architecture and Klutch.sh’s deployment simplicity means you can add comments to your website without relying on third-party services.

With multiple OAuth providers, Markdown support, and real-time updates, Remark42 provides a modern commenting experience. The privacy-first design means your readers can participate in discussions without being tracked across the internet.

Whether you’re running a personal blog or multiple websites, Remark42 on Klutch.sh provides the reliable foundation for community engagement without compromising on privacy.