Deploying Artalk

Artalk is an intuitive yet feature-rich self-hosted comment system designed for blogs, websites, and web applications. Built with a lightweight ~40KB Vanilla JS client and a high-performance Golang backend, Artalk offers a privacy-first alternative to third-party comment platforms like Disqus. With multi-site management, social login integration, email notifications, and comprehensive moderation tools, Artalk provides everything you need to foster engaging discussions on your website.

Whether you’re running a personal blog, documentation site, or multi-author publication, Artalk delivers a seamless commenting experience while keeping your data under your control. This guide walks you through deploying Artalk on Klutch.sh using Docker.

Why Choose Artalk?

Privacy-First

Self-hosted solution keeps your comment data under your control, with no third-party tracking or data collection.

Lightweight Client

~40KB client built with pure Vanilla JS, framework-agnostic and blazing fast to load.

Multi-Site Support

Manage comments for multiple websites from a single Artalk instance with isolated data per site.

Rich Features

Email notifications, social login, captcha, spam moderation, Markdown support, emoji packs, and more.

Prerequisites

Before deploying Artalk on Klutch.sh, ensure you have the following:

• A GitHub account for repository hosting
• A Klutch.sh account for deployment
• A website or blog where you’ll integrate the comment widget

Key Features

Artalk offers a comprehensive set of features for comment management:

Client Features

• Markdown Support: Write comments with full Markdown syntax
• Emoji Pack: Compatible with OwO format for custom emoticons
• Dark Mode: Automatic or manual dark mode switching
• Comment Voting: Upvote and downvote comments
• Image Upload: Allow users to attach images to comments
• LaTeX Support: Render mathematical formulas
• Reply Notifications: In-site notification system
• Comment Search: Search through all comments

Server Features

• Multi-Site Management: Centralized management for multiple websites
• Social Login: GitHub, Google, Twitter, Discord, and more
• Email Notifications: SMTP, Aliyun, and Sendmail support
• Spam Moderation: Akismet, keyword filters, and cloud services
• Captcha Protection: Image, Turnstile, reCAPTCHA, hCaptcha support
• Multiple Databases: SQLite, MySQL, PostgreSQL, SQL Server

Creating the Dockerfile

Create a Dockerfile in your project root that uses the official Artalk Docker image:

Dockerfile

FROM artalk/artalk-go:latest

# Set environment variables
ENV ATK_HOST=0.0.0.0
ENV ATK_PORT=23366
ENV TZ=UTC
ENV ATK_LOCALE=en

# Data directory for persistent storage
VOLUME ["/data"]

# Expose the default Artalk port
EXPOSE 23366

# The base image handles startup
CMD ["artalk", "server"]

Official Docker Image

The artalk/artalk-go:latest image is officially maintained by the Artalk team. It includes the complete backend server with embedded frontend client resources.

Environment Variables

Artalk supports extensive configuration through environment variables prefixed with ATK_. Configure these in the Klutch.sh dashboard:

Core Configuration

Variable	Description	Default
ATK_APP_KEY	Secret key for JWT token generation (required for security)	None
ATK_LOCALE	Language code (en, zh-CN, zh-TW, ja, fr, ko, ru)	en
ATK_TIMEZONE	IANA timezone (e.g., America/New_York)	Asia/Shanghai
ATK_SITE_DEFAULT	Default site name	Default Site
ATK_SITE_URL	Default site URL	None
TZ	Container timezone	UTC

Server Configuration

Variable	Description	Default
ATK_HOST	Listen host address	0.0.0.0
ATK_PORT	Listen port	23366
ATK_DEBUG	Enable debug mode	false
ATK_TRUSTED_DOMAINS	Allowed domains (space-separated)	None
ATK_LOGIN_TIMEOUT	Login session timeout (seconds)	259200

Database Configuration

Variable	Description	Default
ATK_DB_TYPE	Database type (sqlite, mysql, pgsql, mssql)	sqlite
ATK_DB_FILE	SQLite database file path	./data/artalk.db
ATK_DB_HOST	Database host (MySQL/PostgreSQL)	localhost
ATK_DB_PORT	Database port	3306
ATK_DB_NAME	Database name	artalk
ATK_DB_USER	Database username	root
ATK_DB_PASSWORD	Database password	None
ATK_DB_CHARSET	Database character set	utf8mb4
ATK_DB_TABLE_PREFIX	Table name prefix	None

Admin User Configuration

Variable	Description	Example
ATK_ADMIN_USERS_0_NAME	Admin username	admin
ATK_ADMIN_USERS_0_EMAIL	Admin email	admin@example.com
ATK_ADMIN_USERS_0_PASSWORD	Admin password (bcrypt hash)	(bcrypt)$2y$10$...
ATK_ADMIN_USERS_0_BADGE_NAME	Admin badge text	Administrator
ATK_ADMIN_USERS_0_BADGE_COLOR	Admin badge color	#0083FF

Generating Bcrypt Password

To generate a bcrypt password hash, you can use the Artalk CLI inside the container after deployment: docker exec -it artalk artalk admin. Alternatively, use an online bcrypt generator.

Email Configuration

Variable	Description	Default
ATK_EMAIL_ENABLED	Enable email notifications	false
ATK_EMAIL_SEND_TYPE	Send method (smtp, ali_dm, sendmail)	smtp
ATK_EMAIL_SEND_ADDR	Sender email address	None
ATK_EMAIL_SEND_NAME	Sender display name	None
ATK_EMAIL_SMTP_HOST	SMTP server host	None
ATK_EMAIL_SMTP_PORT	SMTP server port	587
ATK_EMAIL_SMTP_USERNAME	SMTP username	None
ATK_EMAIL_SMTP_PASSWORD	SMTP password	None

Captcha Configuration

Variable	Description	Default
ATK_CAPTCHA_ENABLED	Enable captcha	true
ATK_CAPTCHA_CAPTCHA_TYPE	Type (image, turnstile, recaptcha, hcaptcha, geetest)	image
ATK_CAPTCHA_ACTION_LIMIT	Actions before captcha required	3
ATK_CAPTCHA_TURNSTILE_SITE_KEY	Cloudflare Turnstile site key	None
ATK_CAPTCHA_TURNSTILE_SECRET_KEY	Cloudflare Turnstile secret key	None

Cache Configuration

Variable	Description	Default
ATK_CACHE_ENABLED	Enable caching	false
ATK_CACHE_TYPE	Cache type (builtin, redis, memcache)	builtin
ATK_CACHE_EXPIRES	Cache expiration (minutes)	30
ATK_CACHE_SERVER	Cache server address	None

Project Structure

A typical Artalk deployment repository looks like this:

artalk-deploy/
├── Dockerfile
├── data/
│   └── .gitkeep
└── README.md

Complete Dockerfile Example

For a production-ready deployment with custom configuration:

Dockerfile

FROM artalk/artalk-go:latest

# Core configuration
ENV ATK_HOST=0.0.0.0
ENV ATK_PORT=23366
ENV TZ=UTC
ENV ATK_LOCALE=en
ENV ATK_TIMEZONE=America/New_York

# Database configuration (SQLite for simplicity)
ENV ATK_DB_TYPE=sqlite
ENV ATK_DB_FILE=/data/artalk.db

# Image upload configuration
ENV ATK_IMG_UPLOAD_ENABLED=true
ENV ATK_IMG_UPLOAD_PATH=/data/artalk-img/
ENV ATK_IMG_UPLOAD_MAX_SIZE=5

# Logging configuration
ENV ATK_LOG_ENABLED=true
ENV ATK_LOG_FILENAME=/data/artalk.log

# Create data directory
RUN mkdir -p /data/artalk-img

# Volume for persistent data
VOLUME ["/data"]

# Expose the Artalk port
EXPOSE 23366

CMD ["artalk", "server"]

Deploying to Klutch.sh

1. Create a GitHub repository

   Create a new repository containing your Dockerfile:

   mkdir artalk-deploy
   cd artalk-deploy
   git init

2. Add the Dockerfile

   Create the Dockerfile with your configuration:

   touch Dockerfile
   # Add the Dockerfile content from above

3. Push to GitHub

   Commit and push your repository:

   git add .
   git commit -m "Initial Artalk deployment configuration"
   git branch -M main
   git remote add origin https://github.com/yourusername/artalk-deploy.git
   git push -u origin main

4. Connect to Klutch.sh

   Navigate to klutch.sh/app and sign in with your GitHub account. Click New Project to begin the deployment process.

5. Select your repository

   Choose the GitHub repository containing your Artalk Dockerfile. Klutch.sh will automatically detect the Dockerfile in your project root.

6. Configure environment variables

   Add the required environment variables in the Klutch.sh dashboard:

   • ATK_APP_KEY - Generate a random secret string for JWT security
   • ATK_SITE_DEFAULT - Your site name (e.g., “My Blog”)
   • ATK_SITE_URL - Your site URL (e.g., “https://myblog.com”)
   • ATK_TRUSTED_DOMAINS - Your site domains (space-separated)
   • TZ - Your timezone (e.g., “America/New_York”)

   Optional but recommended:

   • ATK_ADMIN_USERS_0_NAME - Admin username
   • ATK_ADMIN_USERS_0_EMAIL - Admin email
   • ATK_EMAIL_ENABLED - Set to true for email notifications

7. Set the internal port

   Configure the internal port to 23366 (Artalk’s default port).

8. Add persistent storage

   Artalk requires persistent storage for the database, uploaded images, and logs. Add a persistent volume:

   Mount Path	Size
   /data	2 GB+

   Persistent Storage Required

   Without persistent storage, all comments and configuration will be lost when the container restarts. Always configure a persistent volume for production use.

9. Deploy your application

   Click Deploy to start the deployment process. Once complete, your Artalk server will be accessible at https://example-app.klutch.sh.

Post-Deployment Setup

Creating an Admin Account

After deploying Artalk, you need to create an administrator account. You can do this through environment variables (recommended) or via the initial setup.

Using Environment Variables (Recommended):

Add these environment variables in the Klutch.sh dashboard:

ATK_ADMIN_USERS_0_NAME=admin
ATK_ADMIN_USERS_0_EMAIL=admin@yourdomain.com
ATK_ADMIN_USERS_0_PASSWORD=(bcrypt)$2y$10$your-bcrypt-hash-here
ATK_ADMIN_USERS_0_BADGE_NAME=Administrator
ATK_ADMIN_USERS_0_BADGE_COLOR=#0083FF

First-Time Access:

If you didn’t configure admin users via environment variables:

1. Navigate to your Artalk URL
2. The first user to enter matching admin email in the comment box will be prompted to set up admin access
3. Follow the setup wizard to create your admin account

Accessing the Dashboard

Once logged in as an admin, you can access the Dashboard by:

1. Entering your admin username and email in the comment box on any page with Artalk embedded
2. A “Dashboard” button will appear at the bottom-right corner
3. Click to access the full administration interface

Integrating Artalk into Your Website

Using CDN (Quick Start)

Add Artalk to your webpage using CDN resources:

<!DOCTYPE html>
<html>
<head>
  <!-- Artalk CSS -->
  <link href="https://example-app.klutch.sh/dist/Artalk.css" rel="stylesheet" />
</head>
<body>
  <!-- Comment Container -->
  <div id="Comments"></div>

  <!-- Artalk JS -->
  <script src="https://example-app.klutch.sh/dist/Artalk.js"></script>
  <script>
    Artalk.init({
      el:        '#Comments',                    // Container selector
      pageKey:   '/post/hello-world',            // Unique page identifier
      pageTitle: 'Hello World',                  // Page title
      server:    'https://example-app.klutch.sh', // Artalk server URL
      site:      'My Blog',                       // Site name
    })
  </script>
</body>
</html>

Using npm (Modern Projects)

Install Artalk via npm:

npm install artalk

Import and initialize in your JavaScript:

import 'artalk/Artalk.css'
import Artalk from 'artalk'

const artalk = Artalk.init({
  el:        document.querySelector('#Comments'),
  pageKey:   window.location.pathname,
  pageTitle: document.title,
  server:    'https://example-app.klutch.sh',
  site:      'My Blog',
})

Framework Integration Examples

React

import { useEffect, useRef } from 'react'
import 'artalk/Artalk.css'
import Artalk from 'artalk'

function Comments() {
  const containerRef = useRef(null)
  const artalkRef = useRef(null)

  useEffect(() => {
    artalkRef.current = Artalk.init({
      el: containerRef.current,
      pageKey: window.location.pathname,
      pageTitle: document.title,
      server: 'https://example-app.klutch.sh',
      site: 'My Blog',
    })

    return () => {
      artalkRef.current?.destroy()
    }
  }, [])

  return <div ref={containerRef} />
}

export default Comments

Vue

<template>
  <div ref="artalkContainer"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import 'artalk/Artalk.css'
import Artalk from 'artalk'

const artalkContainer = ref(null)
let artalk = null

onMounted(() => {
  artalk = Artalk.init({
    el: artalkContainer.value,
    pageKey: window.location.pathname,
    pageTitle: document.title,
    server: 'https://example-app.klutch.sh',
    site: 'My Blog',
  })
})

onUnmounted(() => {
  artalk?.destroy()
})
</script>

Astro

Comments.astro

<div id="Comments"></div>

<link rel="stylesheet" href="https://example-app.klutch.sh/dist/Artalk.css" />
<script is:inline src="https://example-app.klutch.sh/dist/Artalk.js"></script>
<script is:inline>
  Artalk.init({
    el: '#Comments',
    pageKey: window.location.pathname,
    pageTitle: document.title,
    server: 'https://example-app.klutch.sh',
    site: 'My Blog',
  })
</script>

Client Configuration Options

Customize the Artalk client behavior:

Artalk.init({
  // Required
  el:        '#Comments',
  server:    'https://example-app.klutch.sh',
  site:      'My Blog',

  // Page identification
  pageKey:   '/post/hello-world',
  pageTitle: 'Hello World',

  // UI Settings
  darkMode:  'auto',              // 'auto', 'light', 'dark'
  locale:    'en',                // Language
  placeholder: 'Leave a comment...', // Input placeholder

  // Features
  emoticons: 'https://cdn.jsdelivr.net/gh/ArtalkJS/Emoticons/grps/default.json',
  gravatar: {
    mirror: 'https://www.gravatar.com/avatar/',
    params: 'sha256=1&d=mp&s=240',
  },

  // Comment display
  nestMax:       2,               // Max nesting depth
  nestSort:      'DATE_ASC',      // Nested sort order
  flatMode:      false,           // Flat or nested view
  pagination: {
    pageSize:    20,              // Comments per page
    readMore:    true,            // Load more button
    autoLoad:    true,            // Auto-load on scroll
  },

  // Features toggles
  vote:          true,            // Enable voting
  voteDown:      false,           // Enable downvotes
  preview:       true,            // Real-time preview
  editorTravel:  true,            // Movable editor
  imgLazyLoad:   true,            // Lazy load images
})

Database Configuration

Using SQLite (Default)

SQLite is perfect for small to medium sites and requires no external database:

ATK_DB_TYPE=sqlite
ATK_DB_FILE=/data/artalk.db

Using PostgreSQL

For larger deployments, configure an external PostgreSQL database:

ATK_DB_TYPE=pgsql
ATK_DB_HOST=your-postgres-host.example.com
ATK_DB_PORT=5432
ATK_DB_NAME=artalk
ATK_DB_USER=artalk
ATK_DB_PASSWORD=your-secure-password

Using MySQL

For MySQL/MariaDB databases:

ATK_DB_TYPE=mysql
ATK_DB_HOST=your-mysql-host.example.com
ATK_DB_PORT=3306
ATK_DB_NAME=artalk
ATK_DB_USER=artalk
ATK_DB_PASSWORD=your-secure-password
ATK_DB_CHARSET=utf8mb4

Configuring Email Notifications

Enable email notifications to alert users when they receive replies:

ATK_EMAIL_ENABLED=true
ATK_EMAIL_SEND_TYPE=smtp
ATK_EMAIL_SEND_NAME=Artalk Notifications
ATK_EMAIL_SEND_ADDR=noreply@yourdomain.com
ATK_EMAIL_SMTP_HOST=smtp.yourdomain.com
ATK_EMAIL_SMTP_PORT=587
ATK_EMAIL_SMTP_USERNAME=noreply@yourdomain.com
ATK_EMAIL_SMTP_PASSWORD=your-smtp-password

Enabling Social Login

Allow users to sign in with their social accounts:

ATK_AUTH_ENABLED=true
ATK_AUTH_CALLBACK=https://example-app.klutch.sh/api/v2/auth/{provider}/callback

# GitHub OAuth
ATK_AUTH_GITHUB_ENABLED=true
ATK_AUTH_GITHUB_CLIENT_ID=your-github-client-id
ATK_AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret

# Google OAuth
ATK_AUTH_GOOGLE_ENABLED=true
ATK_AUTH_GOOGLE_CLIENT_ID=your-google-client-id
ATK_AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

Custom Domain Setup

To use a custom domain with your Artalk deployment:

1. Add your domain in Klutch.sh

   Navigate to your project settings and add your custom domain (e.g., comments.yourdomain.com).

2. Configure DNS records

   Add a CNAME record pointing to your Klutch.sh deployment:

   Type	Name	Value
   CNAME	comments	example-app.klutch.sh

3. Update trusted domains

   Add your custom domain to the trusted domains environment variable:

   ATK_TRUSTED_DOMAINS=https://yourdomain.com https://comments.yourdomain.com

4. Update client configuration

   Update the server URL in your Artalk client initialization:

   Artalk.init({
     server: 'https://comments.yourdomain.com',
     // ... other options
   })

Local Development with Docker Compose

For local development and testing:

docker-compose.yml

services:
  artalk:
    container_name: artalk
    image: artalk/artalk-go
    restart: unless-stopped
    ports:
      - "8080:23366"
    volumes:
      - ./data:/data
    environment:
      - TZ=America/New_York
      - ATK_LOCALE=en
      - ATK_SITE_DEFAULT=My Blog
      - ATK_SITE_URL=http://localhost:8080
      - ATK_APP_KEY=your-secret-key-here
      - ATK_TRUSTED_DOMAINS=http://localhost:3000 http://localhost:8080

Start the local environment:

docker compose up -d

Access Artalk at http://localhost:8080.

Data Migration

Artalk supports importing comments from other platforms:

• Disqus: Export from Disqus and import via Artalk Dashboard
• WordPress: Use the built-in WordPress importer
• Typecho: Direct database migration support
• Valine/Waline: JSON import support
• Commento: JSON format support
• Twikoo: Direct import support

Access the migration tools from the Artalk Dashboard under the “Transfer” section.

Troubleshooting

CORS Errors

If you see CORS errors in the browser console:

1. Ensure your site URL is added to ATK_TRUSTED_DOMAINS
2. Include the protocol (https://) and port if non-standard
3. Restart the Artalk container after changes

Database Connection Issues

If Artalk fails to connect to the database:

1. Verify database credentials in environment variables
2. Ensure the database host is accessible from Klutch.sh
3. Check that the database user has appropriate permissions

Comments Not Loading

If the comment widget shows but doesn’t load comments:

1. Verify the server URL in Artalk.init() is correct
2. Check that site matches the configured site name
3. Ensure the Artalk container is running

Email Notifications Not Sending

If email notifications aren’t working:

1. Verify ATK_EMAIL_ENABLED=true
2. Check SMTP credentials are correct
3. Test SMTP connection from another client
4. Review logs at /data/artalk.log

Resources

• Artalk GitHub Repository
• Official Documentation
• Environment Variables Reference
• Client Configuration Options
• Data Migration Guide

Next Steps

After deploying Artalk, consider:

• Configuring email notifications for reply alerts
• Setting up social login for easier commenting
• Customizing the comment widget appearance
• Enabling spam moderation with Akismet
• Adding custom emoji packs
• Configuring Turnstile or reCAPTCHA for captcha protection
• Setting up Redis cache for improved performance