Deploying a Dotclear App

Introduction

Dotclear is an open-source web publishing software that puts you in full control of your blog. With over 20 years of development history and a strong focus on user experience, Dotclear offers a robust yet user-friendly platform for content creators, regardless of their technical background.

Built with PHP and supporting multiple database backends (MySQL, MariaDB, PostgreSQL, SQLite), Dotclear stands out with its clean architecture, powerful template system, and extensive customization options. Whether you’re running a personal blog, managing multiple sites, or building a publication platform with several authors, Dotclear provides the tools you need without unnecessary complexity.

Key Features:

Easy Publication - Intuitive interface for publishing content quickly
Flexible Editing - Choose between Wiki, Markdown, or WYSIWYG editors
Multi-blog Support - Manage multiple blogs from a single installation
Multi-user - Full user management with granular permissions
Theme System - Fully customizable themes with flexible templates
Media Management - Upload and organize images, videos, and files
Built-in Antispam - Protect your site from spam comments
SEO Optimized - Naturally optimized for search engines
Extensible - Add functionality through plugins
Standards Compliant - Follows web standards and accessibility guidelines
Multilingual - Full localization support
Import/Export - Easily migrate content from other platforms

This guide will walk you through deploying Dotclear on Klutch.sh using Docker, ensuring you have a production-ready blogging platform with persistent storage, proper security, and optimal performance.

Why Deploy Dotclear on Klutch.sh?

Deploying Dotclear on Klutch.sh offers several advantages over traditional hosting solutions:

✅ Automated Docker Deployments - Klutch.sh automatically detects your Dockerfile and handles the build process
✅ Persistent Storage - Your blog content, media files, and database remain safe across deployments
✅ Instant Deployments - Push to GitHub and watch your blog go live in minutes
✅ Zero DevOps Overhead - No server management, security patches, or infrastructure maintenance
✅ Scalable Architecture - Your blog grows with your audience
✅ Custom Domains - Connect your own domain name with SSL/TLS certificates
✅ Environment Variables - Securely manage database credentials and configuration
✅ Automatic HTTPS - SSL certificates are automatically provisioned and renewed
✅ Built-in Monitoring - Track your application’s health and performance
✅ Cost-Effective - Pay only for the resources you use

Prerequisites

Before you begin, make sure you have:

A Klutch.sh account
A GitHub account with a repository for your Dotclear project
Basic familiarity with Git and Docker
A MySQL/MariaDB or PostgreSQL database (or use SQLite for simplicity)
(Optional) A custom domain name for your blog

Understanding Dotclear Architecture

Dotclear follows a classic PHP web application architecture:

Core Components:

PHP Application Layer - Handles requests, routing, and business logic
Database Layer - Stores content, users, settings, and metadata
File Storage - Media uploads, themes, plugins, and cache files
Template Engine - Renders dynamic content using the Dotclear template system
Admin Interface - Web-based dashboard for content management
Public Frontend - Your blog’s public-facing pages

Default Configuration:

Port: 80 (HTTP)
PHP Version: 8.1 to 8.4
Required Extensions: mbstring, simplexml, mysqli/pgsql/sqlite, intl
Database: MySQL/MariaDB, PostgreSQL, or SQLite
Web Server: Apache with mod_rewrite (or Nginx)

Directory Structure:

/var/www/html/
├── admin/          # Administration interface
├── inc/            # Core includes
├── plugins/        # Installed plugins
├── themes/         # Blog themes
├── public/         # Public assets
├── cache/          # Temporary cache files
└── index.php       # Entry point

Preparing Your Repository

Let’s create the necessary files for deploying Dotclear on Klutch.sh.

Step 1: Create the Dockerfile

Create a Dockerfile in the root of your repository. This file defines how your Dotclear application will be containerized:

FROM php:8.3-apache

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libicu-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    unzip \
    wget \
    && rm -rf /var/lib/apt/lists/*

# Configure and install PHP extensions
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
    gd \
    intl \
    mbstring \
    mysqli \
    pdo \
    pdo_mysql \
    zip

# Enable Apache modules
RUN a2enmod rewrite headers expires

# Set working directory
WORKDIR /var/www/html

# Download and extract Dotclear
ARG DOTCLEAR_VERSION=2.31
RUN wget -O dotclear.tar.gz "https://download.dotclear.org/attic/dotclear-${DOTCLEAR_VERSION}.tar.gz" \
    && tar -xzf dotclear.tar.gz --strip-components=1 \
    && rm dotclear.tar.gz

# Create necessary directories
RUN mkdir -p /var/www/html/public \
    && mkdir -p /var/www/html/cache \
    && mkdir -p /var/www/html/db

# Set permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html \
    && chmod -R 775 /var/www/html/public \
    && chmod -R 775 /var/www/html/cache \
    && chmod -R 775 /var/www/html/db

# Configure Apache
RUN echo '<Directory /var/www/html>\n\
    Options Indexes FollowSymLinks\n\
    AllowOverride All\n\
    Require all granted\n\
</Directory>' > /etc/apache2/conf-available/dotclear.conf \
    && a2enconf dotclear

# Expose port 80
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
    CMD curl -f http://localhost/ || exit 1

# Start Apache
CMD ["apache2-foreground"]

Key Dockerfile Features:

PHP 8.3 - Latest stable PHP version for optimal performance
Apache with mod_rewrite - Enables clean URLs
Required Extensions - All necessary PHP extensions pre-installed
Dotclear 2.31 - Latest stable release
Proper Permissions - Correct file ownership for web server
Health Check - Ensures the application is responding

Step 2: Create a .dockerignore File

Add a .dockerignore file to exclude unnecessary files from the Docker build context:

.git
.gitignore
.github
README.md
.env
.env.example
node_modules
npm-debug.log
docker-compose.yml
.DS_Store
*.md
.vscode
.idea

Step 3: Create an Environment Variables Template

Create a .env.example file to document the required environment variables:

# Database Configuration
DB_TYPE=mysql
DB_HOST=your-database-host
DB_PORT=3306
DB_NAME=dotclear
DB_USER=dotclear_user
DB_PASSWORD=your-secure-password
DB_PREFIX=dc_

# Dotclear Configuration
DC_ADMIN_USERNAME=admin
DC_ADMIN_PASSWORD=your-admin-password
DC_ADMIN_EMAIL=admin@example.com
DC_BLOG_NAME=My Dotclear Blog
DC_BLOG_URL=https://example-app.klutch.sh

# Security
DC_MASTER_KEY=generate-random-32-char-key-here

# Optional: Timezone
TZ=UTC

Step 4: Create a README

Add a README.md file with setup instructions:

# Dotclear Blog

This repository contains a Dockerized Dotclear installation for deployment on Klutch.sh.

## Features

- Dotclear 2.31 (latest stable)
- PHP 8.3 with all required extensions
- Apache with mod_rewrite enabled
- Ready for MySQL/MariaDB, PostgreSQL, or SQLite
- Persistent storage for content and media
- Automatic health checks

## Deployment

This application is designed to be deployed on Klutch.sh. See the documentation for detailed deployment instructions.

## Local Development

To run locally:

1. Copy `.env.example` to `.env` and configure your database
2. Build: `docker build -t dotclear .`
3. Run: `docker run -p 8080:80 --env-file .env dotclear`
4. Access at http://localhost:8080

## Configuration

After deployment, complete the initial setup wizard at `/admin/install/`.

## License

Dotclear is licensed under AGPL-3.0.

Deploying on Klutch.sh

Now that your repository is prepared, let’s deploy Dotclear on Klutch.sh.

Step 1: Push to GitHub

Push your code to GitHub:

git add .
git commit -m "Initial Dotclear setup for Klutch.sh"
git push origin main

Step 2: Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard
Click “New Project”
Select your GitHub repository containing the Dotclear code
Klutch.sh will automatically detect the Dockerfile in your repository

Step 3: Configure Environment Variables

In the Klutch.sh dashboard, add the following environment variables:

Database Configuration:

DB_TYPE=mysql
DB_HOST=your-database-host.klutch.sh
DB_PORT=3306
DB_NAME=dotclear
DB_USER=dotclear_user
DB_PASSWORD=your-secure-password
DB_PREFIX=dc_

Dotclear Configuration:

DC_ADMIN_USERNAME=admin
DC_ADMIN_PASSWORD=create-strong-password-here
DC_ADMIN_EMAIL=your-email@example.com
DC_BLOG_NAME=My Awesome Blog
DC_BLOG_URL=https://your-app.klutch.sh

Security:

DC_MASTER_KEY=generate-random-32-char-key-here
TZ=America/New_York

Generate a secure master key:

openssl rand -base64 32

Step 4: Configure Traffic Settings

In the project settings, select HTTP as the traffic type
Dotclear runs on port 80 internally (this is already configured in the Dockerfile)
Klutch.sh will automatically route external HTTPS traffic to your application

Step 5: Add Persistent Storage

Dotclear requires persistent storage for uploaded media, themes, plugins, and cache files:

In the Klutch.sh dashboard, navigate to Storage
Add a new persistent volume:
- Mount Path: /var/www/html/public
- Size: Start with 10GB (adjust based on your needs)
Add another volume for cache:
- Mount Path: /var/www/html/cache
- Size: 2GB
If using SQLite, add a volume for the database:
- Mount Path: /var/www/html/db
- Size: 5GB

Step 6: Deploy

Click “Deploy” in the Klutch.sh dashboard
Klutch.sh will build your Docker image and deploy the application
Monitor the build logs to ensure everything completes successfully
Once deployed, you’ll receive a URL like https://your-app.klutch.sh

Step 7: Complete Initial Setup

After deployment:

Visit https://your-app.klutch.sh/admin/install/
The Dotclear installation wizard will guide you through:
- Database Configuration - Enter your database credentials (or select SQLite)
- Admin Account - Create your admin username and password
- Blog Settings - Configure your blog name, description, and timezone
- Language Selection - Choose your preferred language
Click “Install” to complete the setup
Log in to your admin dashboard at https://your-app.klutch.sh/admin/

Initial Configuration

After completing the installation wizard, let’s configure essential settings for your blog.

Basic Blog Settings

Configure General Settings:

Go to System Settings → Blog Settings
Configure:
- Blog Name - Your blog’s title
- Blog Description - A brief tagline for your blog
- Blog URL - Verify this matches your Klutch.sh URL
- Language - Set your blog’s primary language
- Timezone - Set your local timezone
- Date and Time Format - Configure display formats
Click “Save” to apply changes

URL Rewriting and Clean URLs

Enable Clean URLs:

Go to System Settings → Blog Settings → Advanced
Enable “URL rewriting” (Clean URLs)
Set URL format to: post-title or category/post-title
Save changes
Your URLs will now look like:
- https://your-app.klutch.sh/my-first-post
- Instead of: https://your-app.klutch.sh/index.php?post/123

User Management

Create Additional Users:

Go to System → Users
Click “New User”
Fill in user details:
- Username
- Email address
- Password
- First and last name
Assign permissions:
- Super Admin - Full system access
- Admin - Manage content and settings
- Usage - Publish and manage own posts
- Content Admin - Manage all content
Click “Create”

Creating Your First Blog Post

Let’s publish your first post to see Dotclear in action.

Using the Post Editor

Create a New Post:

From the admin dashboard, click “New Post”
Enter your post details:
- Title - Your post headline
- Content - Your post body
- Excerpt - Optional short summary
Choose your editing format:
- WYSIWYG - Visual editor (similar to Word)
- Wiki - Simple wiki markup
- Markdown - Markdown syntax
Configure post settings:
- Category - Assign to a category
- Tags - Add relevant tags
- Publishing Date - Schedule or publish immediately
- Status - Draft, Pending, Scheduled, or Published
Click “Publish” or “Save as Draft”

Adding Media

Upload Images and Files:

In the post editor, click “Add Media”
Upload files:
- Click “Choose File” or drag and drop
- Supported formats: JPEG, PNG, GIF, SVG, PDF, etc.
- Set maximum upload size in PHP settings if needed
Insert media into your post:
- Select the uploaded file
- Choose alignment and size
- Add alt text for accessibility
- Click “Insert”
Media files are stored in /var/www/html/public (persistent storage)

Categories and Tags

Organize Your Content:

Create Categories:
- Go to Blog → Categories
- Click “New Category”
- Enter name, description, and URL slug
- Click “Save”
Manage Tags:
- Tags are created automatically when you add them to posts
- View all tags at Blog → Tags
- Rename or delete tags as needed
- Merge similar tags to keep things organized

Theme Customization

Dotclear’s theming system is flexible and powerful, allowing you to customize your blog’s appearance.

Installing Themes

Add New Themes:

Go to Plugins and Themes → Themes
Click “Add Themes”
Install themes by:
- Uploading a package - Upload a .zip theme file
- From URL - Install from a direct download link
Activate your chosen theme by clicking “Use this theme”

Customizing Your Theme

Theme Configuration:

Go to Plugins and Themes → Theme Configuration
Customize available options (varies by theme):
- Logo and favicon
- Color schemes
- Layout options
- Typography settings
- Header and footer content
Advanced Customization:
- Edit theme files in /var/www/html/themes/your-theme/
- Modify templates, CSS, and JavaScript
- Use the Dotclear template language for dynamic content

Creating a Custom Theme

Build Your Own Theme:

Create a new directory in /var/www/html/themes/mytheme/
Add required files:
- _define.php - Theme metadata
- tpl/ - Template files
- css/ - Stylesheets
- img/ - Theme images
- js/ - JavaScript files
Example _define.php:

<?php
$this->registerModule(
    'My Custom Theme',
    'A beautiful custom theme',
    'Your Name',
    '1.0',
    [
        'type' => 'theme',
        'dc_min' => '2.31'
    ]
);

Create template files using Dotclear’s template language:
- home.html - Homepage template
- post.html - Single post template
- archive.html - Archive pages
- category.html - Category pages
Activate your theme from the admin dashboard

Plugin Management

Extend Dotclear’s functionality with plugins.

Installing Plugins

Add New Plugins:

Go to Plugins and Themes → Plugins
Browse available plugins in the Repository
Install plugins by clicking “Install” or:
- Upload a .zip plugin file
- Install from a URL
Activate the plugin after installation

Popular Plugins

Recommended Plugins for Your Blog:

Akismet - Advanced spam filtering
Markdown - Enhanced Markdown editor support
Contact Me - Add contact forms to your blog
Breadcrumb - Improve navigation with breadcrumbs
Gallery - Create image galleries
Social Share - Add social sharing buttons
SEO Tools - Enhance search engine optimization
Backup - Automated database and file backups
Analytics - Integrate Google Analytics or Matomo
Cache Master - Improve performance with caching

Creating Custom Plugins

Develop Your Own Plugin:

Create a plugin directory: /var/www/html/plugins/myplugin/
Add _define.php:

<?php
$this->registerModule(
    'My Plugin',
    'Description of what it does',
    'Your Name',
    '1.0',
    [
        'type' => 'plugin',
        'dc_min' => '2.31'
    ]
);

Add _prepend.php for initialization code
Add _admin.php for admin interface code
Create your plugin logic and features
Test thoroughly before activating in production

Multi-Blog Setup

Dotclear supports managing multiple blogs from a single installation.

Creating Additional Blogs

Set Up Multiple Blogs:

Go to System → Blogs
Click “New Blog”
Configure the new blog:
- Blog Name - Unique name for this blog
- Blog ID - Unique identifier
- Blog URL - URL for this blog
- Description - Blog tagline
Click “Create”
Switch between blogs using the blog selector in the admin header

Managing Multiple Blogs

Multi-Blog Administration:

User Permissions:
- Assign users to specific blogs
- Set different permission levels per blog
- Go to System → Users → Edit User
- Select which blogs the user can access
Shared Resources:
- Themes and plugins are shared across all blogs
- Each blog has its own content and settings
- Media files can be shared or kept separate
Blog-Specific Settings:
- Each blog has independent:
  - Theme selection
  - URL rewriting settings
  - Comment policies
  - Widget configurations
  - Language settings

Comments and Spam Protection

Dotclear includes robust comment management and spam filtering.

Comment Configuration

Set Up Comment System:

Go to System Settings → Blog Settings → Comments
Configure comment options:
- Allow comments - Enable/disable comments globally
- Comment moderation - Approve before publishing
- Anonymous commenting - Allow or require login
- Comment format - HTML, Markdown, or plain text
- Email notifications - Notify on new comments
Configure Trackbacks and Pingbacks:
- Enable/disable trackback/pingback support
- Set auto-discovery settings
Save changes

Spam Protection

Enable Antispam:

Dotclear includes built-in antispam filters
Go to Plugins → Antispam
Configure spam filters:
- IP Blacklist - Block known spam IPs
- Word Blacklist - Filter spam keywords
- Akismet - Install Akismet plugin for enhanced protection
Moderate Comments:
- Review flagged comments at Comments → Spam
- Mark false positives as ham to train the filter
- Delete confirmed spam

SEO Optimization

Dotclear is naturally optimized for search engines, but you can enhance it further.

Basic SEO Settings

Optimize for Search Engines:

Meta Tags:
- Go to System Settings → Blog Settings → SEO
- Set meta description for your blog
- Configure default meta keywords
- Enable Open Graph tags for social sharing
Permalink Structure:
- Use clean URLs (enable URL rewriting)
- Choose meaningful URL patterns
- Include categories in URLs for better structure
XML Sitemap:
- Install a sitemap plugin
- Generate sitemaps automatically
- Submit to Google Search Console and Bing Webmaster Tools
RSS Feeds:
- Dotclear automatically generates RSS/Atom feeds
- Feeds are available at:
  - /feed/atom - Full Atom feed
  - /feed/rss2 - RSS 2.0 feed
  - /feed/category/{category}/atom - Category feeds

Content Optimization

SEO Best Practices:

Unique Titles - Write descriptive, unique titles for each post
Meta Descriptions - Add custom descriptions to posts
Heading Tags - Use proper H1, H2, H3 hierarchy
Alt Text - Add descriptive alt text to all images
Internal Linking - Link to related posts within your content
Readable URLs - Use clean URLs with keywords
Mobile-Friendly - Ensure your theme is responsive

Importing Content

Migrate content from other platforms to Dotclear.

Supported Import Formats

Import from Other Platforms:

Go to Plugins → Import/Export
Install the appropriate import plugin:
- WordPress - Import from WordPress XML export
- Blogger - Import from Blogger
- Dotclear Export - Import from another Dotclear blog
- RSS/Atom - Import from feed URLs
- Generic - Import from CSV files
WordPress Import Example:
- Export your WordPress content to XML
- Go to Plugins → WordPress Importer
- Upload the XML file
- Map users and categories
- Click “Import”
- Review imported content and adjust as needed

Backup and Recovery

Regular backups are critical for protecting your blog content.

Manual Backup

Back Up Your Blog:

Database Backup:
- Go to System → Maintenance
- Click “Export database”
- Download the SQL file
- Store securely off-site
File Backup:
- Back up persistent volumes:
  - /var/www/html/public - Media files
  - /var/www/html/themes - Custom themes
  - /var/www/html/plugins - Custom plugins
  - /var/www/html/cache - Cache files (optional)
- Use rsync, SCP, or SFTP to download files
- Or use Klutch.sh’s backup features if available
Configuration Backup:
- Export your environment variables from Klutch.sh
- Save a copy of your Dockerfile and repository

Automated Backup Strategy

Set Up Automatic Backups:

Install Backup Plugin:
- Install a backup plugin from the repository
- Configure automated backup schedules
- Set retention policies (e.g., keep 30 days)
Database Backup Script:

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups"
DB_NAME="dotclear"

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup database
docker exec your-container-name \
  mysqldump -u $DB_USER -p$DB_PASSWORD $DB_NAME \
  > $BACKUP_DIR/dotclear_db_$DATE.sql

# Backup files
docker cp your-container-name:/var/www/html/public \
  $BACKUP_DIR/public_$DATE

# Compress backups
tar -czf $BACKUP_DIR/dotclear_backup_$DATE.tar.gz \
  $BACKUP_DIR/dotclear_db_$DATE.sql \
  $BACKUP_DIR/public_$DATE

# Clean up old backups (keep last 30 days)
find $BACKUP_DIR -name "dotclear_backup_*.tar.gz" -mtime +30 -delete

echo "Backup completed: dotclear_backup_$DATE.tar.gz"

Schedule this script with cron on your local machine or CI/CD system

Restore Procedure

Restore from Backup:

Restore Database:
- Stop your application
- Import the SQL backup:

mysql -u $DB_USER -p$DB_PASSWORD $DB_NAME < dotclear_db_backup.sql

Restore Files:
- Extract the backup archive
- Copy files to persistent volumes
- Ensure correct permissions (www-data:www-data)
Verify and Test:
- Start your application
- Test login and basic functionality
- Check that all content is present
- Verify media files are loading

Performance Optimization

Optimize Dotclear for better performance and faster page loads.

Enable Caching

Configure Cache Settings:

Go to System Settings → Advanced
Enable Template Cache:
- Caches compiled templates
- Reduces processing time
- Clear cache when making theme changes
Enable Cache Master plugin:
- Install from plugin repository
- Configure page caching
- Set cache expiration times
- Exclude admin pages from caching

Database Optimization

Optimize Database Performance:

Regular Maintenance:
- Go to System → Maintenance
- Run “Optimize database tables”
- Clean up old revisions and drafts
- Remove spam comments
Database Indexing:

-- Run these queries on your database
OPTIMIZE TABLE dc_post;
OPTIMIZE TABLE dc_comment;
OPTIMIZE TABLE dc_meta;
ANALYZE TABLE dc_post;
ANALYZE TABLE dc_comment;

Media Optimization

Optimize Images and Files:

Image Compression:
- Install an image optimization plugin
- Configure automatic compression on upload
- Set maximum dimensions for images
- Use WebP format for modern browsers
Lazy Loading:
- Enable lazy loading for images
- Reduces initial page load time
- Improves performance on mobile devices
CDN Integration:
- Consider using a CDN for static assets
- Offload media delivery to edge servers
- Configure CDN URLs in blog settings

PHP Performance

Optimize PHP Configuration:

Add these to your Dockerfile for better performance:

# Add to Dockerfile
RUN { \
    echo 'opcache.enable=1'; \
    echo 'opcache.memory_consumption=128'; \
    echo 'opcache.interned_strings_buffer=8'; \
    echo 'opcache.max_accelerated_files=4000'; \
    echo 'opcache.revalidate_freq=60'; \
    echo 'upload_max_filesize=64M'; \
    echo 'post_max_size=64M'; \
    echo 'memory_limit=256M'; \
    echo 'max_execution_time=300'; \
} > /usr/local/etc/php/conf.d/custom.ini

Security Best Practices

Secure your Dotclear installation against common threats.

Admin Security

Secure Admin Access:

Strong Passwords:
- Use passwords with 16+ characters
- Include uppercase, lowercase, numbers, and symbols
- Change passwords regularly
- Use a password manager
Two-Factor Authentication:
- Install a 2FA plugin
- Configure authenticator app (Google Authenticator, Authy)
- Require 2FA for all admin users
Limit Login Attempts:
- Install a login limiter plugin
- Lock accounts after failed attempts
- Add IP-based restrictions
- Monitor login logs

File Security

Protect Your Files:

File Permissions:

# Set correct permissions
chown -R www-data:www-data /var/www/html
chmod -R 755 /var/www/html
chmod -R 775 /var/www/html/public
chmod -R 775 /var/www/html/cache
chmod 644 /var/www/html/.htaccess

Disable Directory Listing:
- Edit .htaccess:

Options -Indexes

Restrict File Uploads:
- Limit upload file types
- Set maximum file size
- Scan uploads for malware

Database Security

Secure Your Database:

Database Credentials:
- Use strong database passwords
- Store credentials in environment variables (not code)
- Limit database user permissions
- Use separate users for read/write access
SQL Injection Prevention:
- Dotclear uses prepared statements (secure by default)
- Keep Dotclear updated to latest version
- Review custom plugins for SQL vulnerabilities
Database Backups:
- Keep encrypted backups off-site
- Test restore procedures regularly
- Store backups for at least 30 days

HTTPS and SSL

Enforce Secure Connections:

Klutch.sh automatically provides SSL certificates
Force HTTPS in Dotclear:
- Go to System Settings → Blog Settings
- Set Blog URL to https://your-app.klutch.sh
- Configure .htaccess to redirect HTTP to HTTPS:

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Security Headers

Add Security Headers:

Add to Apache configuration in your Dockerfile:

# Add security headers
Header always set X-Frame-Options "SAMEORIGIN"
Header always set X-Content-Type-Options "nosniff"
Header always set X-XSS-Protection "1; mode=block"
Header always set Referrer-Policy "strict-origin-when-cross-origin"
Header always set Permissions-Policy "geolocation=(), microphone=(), camera=()"

Troubleshooting

Common issues and their solutions.

Application Won’t Start

Problem: Container fails to start or crashes immediately

Solutions:

Check Build Logs:
- Review Klutch.sh deployment logs
- Look for errors during Docker build
- Verify all dependencies installed successfully
Verify Environment Variables:
- Ensure all required variables are set
- Check for typos in variable names
- Verify database credentials are correct
Check Permissions:

# Ensure correct ownership
chown -R www-data:www-data /var/www/html
chmod -R 755 /var/www/html

Test Locally:
- Build Docker image locally
- Run with same environment variables
- Check container logs: docker logs container-name

Database Connection Errors

Problem: “Unable to connect to database” error

Solutions:

Verify Database Credentials:
- Check DB_HOST, DB_PORT, DB_NAME
- Verify DB_USER and DB_PASSWORD
- Test connection manually
Check Database Server:
- Ensure database is running
- Verify network connectivity
- Check firewall rules
Test Connection:

# Test MySQL connection
mysql -h $DB_HOST -P $DB_PORT -u $DB_USER -p$DB_PASSWORD $DB_NAME

Use SQLite for Testing:
- Switch to SQLite temporarily
- Set DB_TYPE=sqlite in environment variables
- Check if issue is database-specific

Installation Wizard Issues

Problem: Installation wizard fails or shows errors

Solutions:

Check Write Permissions:
- Ensure /var/www/html/public is writable
- Verify /var/www/html/cache is writable
- Check /var/www/html/db if using SQLite
PHP Extension Issues:
- Verify required extensions are installed
- Check phpinfo() output
- Rebuild Docker image if extensions missing
Clear Cache:

# Clear Dotclear cache
rm -rf /var/www/html/cache/*

Reset Installation:
- Delete inc/config.php if it exists
- Restart container
- Run installation wizard again

Upload Errors

Problem: Cannot upload media files

Solutions:

Check File Size Limits:
- Increase PHP upload limits in Dockerfile
- Set upload_max_filesize=64M
- Set post_max_size=64M
Verify Permissions:

chmod -R 775 /var/www/html/public
chown -R www-data:www-data /var/www/html/public

Check Persistent Volume:
- Ensure volume is properly mounted
- Verify sufficient disk space
- Check Klutch.sh storage settings

Performance Issues

Problem: Slow page load times

Solutions:

Enable Caching:
- Enable template cache
- Install Cache Master plugin
- Configure page caching
Optimize Database:
- Run maintenance tasks
- Clean up old data
- Optimize tables
Optimize Images:
- Compress uploaded images
- Enable lazy loading
- Use appropriate image formats
Check Resources:
- Monitor CPU and memory usage in Klutch.sh
- Upgrade plan if consistently hitting limits
- Consider moving database to dedicated server

Theme Not Displaying Correctly

Problem: Theme appears broken or styles not loading

Solutions:

Clear Cache:
- Go to System → Maintenance
- Clear template cache
- Refresh browser cache
Check File Permissions:
- Verify theme files are readable
- Check /var/www/html/themes/ permissions
Verify Theme Compatibility:
- Ensure theme supports Dotclear 2.31
- Check for required plugins
- Review theme documentation
Check Console Errors:
- Open browser developer tools
- Look for 404 errors for CSS/JS files
- Verify asset URLs are correct

Plugin Conflicts

Problem: Site breaks after installing a plugin

Solutions:

Disable Problem Plugin:
- Rename plugin directory temporarily
- Access: /var/www/html/plugins/problematic-plugin
- Rename to problematic-plugin.disabled
Check Error Logs:
- Review Apache error logs
- Check PHP error log
- Look for plugin-specific errors
Test Plugin Compatibility:
- Verify plugin supports your Dotclear version
- Check for known issues on plugin page
- Update plugin to latest version
Contact Plugin Author:
- Report bug with detailed error information
- Check plugin’s issue tracker
- Look for alternative plugins

Production Checklist

Before launching your blog to the public, ensure everything is properly configured.

Pre-Launch Checklist

Essential Tasks:

☑ Dockerfile Configuration

Latest Dotclear version specified
All required PHP extensions installed
Apache mod_rewrite enabled
Proper file permissions set

☑ Environment Variables

Database credentials configured
Admin password is strong and secure
Master key generated and set
Timezone configured correctly

☑ Persistent Storage

/var/www/html/public volume attached (10GB+)
/var/www/html/cache volume attached (2GB+)
Database volume if using SQLite (5GB+)

☑ Security

Strong admin password set
2FA enabled for admin accounts
HTTPS enforced
Security headers configured
File permissions correct
Database credentials secure

☑ Blog Configuration

Blog name and description set
Clean URLs enabled
Timezone configured
Language set correctly
Comment policy configured
Spam protection enabled

☑ SEO

Meta descriptions configured
XML sitemap generated
RSS feeds enabled
Open Graph tags enabled
Robots.txt configured

☑ Content

Test posts published
Categories created
Media uploads tested
Theme customized
About page created
Contact information added

☑ Performance

Template cache enabled
Page caching configured
Images optimized
Database optimized
PHP opcache enabled

☑ Backup

Backup strategy implemented
First manual backup completed
Restore procedure tested
Backup storage configured

☑ Testing

All pages load correctly
Forms work properly
Comments function
Media uploads work
Admin dashboard accessible
Mobile responsive
Cross-browser tested

☑ Monitoring

Health checks configured
Error logging enabled
Analytics installed (optional)
Uptime monitoring set up

Post-Launch Tasks

After Going Live:

Submit to Search Engines:
- Submit sitemap to Google Search Console
- Submit sitemap to Bing Webmaster Tools
- Verify site ownership
Set Up Analytics:
- Install Google Analytics or Matomo
- Configure goals and events
- Set up conversion tracking
Monitor Performance:
- Check page load times
- Monitor resource usage
- Review error logs
- Test from different locations
Promote Your Blog:
- Share on social media
- Submit to blog directories
- Build backlinks
- Engage with your audience

Additional Resources

Official Documentation

Community and Support

Klutch.sh Resources

Theme and Plugin Resources

Conclusion

You now have a fully functional Dotclear blog running on Klutch.sh! This deployment gives you:

✅ Complete Control - Full ownership of your blogging platform and content
✅ Professional Setup - Production-ready configuration with security and performance optimizations
✅ Persistent Storage - Your content, media, and customizations are safe across deployments
✅ Easy Management - User-friendly admin interface for content management
✅ Extensibility - Hundreds of themes and plugins to customize your blog
✅ Multi-User Support - Collaborate with multiple authors and editors
✅ SEO Optimized - Built-in features for better search engine rankings
✅ Scalability - Grow from a personal blog to a full publication platform

Dotclear’s simplicity, combined with Klutch.sh’s deployment automation, creates a powerful yet manageable blogging solution. Whether you’re starting a personal blog, building a multi-author publication, or managing multiple websites, this setup provides the foundation you need.

Start creating great content, engage with your readers, and watch your blog grow. Happy blogging! 🎉