Deploying a CouchCMS App

Introduction

CouchCMS is a lightweight, open-source content management system designed for developers who want simplicity without sacrificing flexibility. Built with PHP and designed to be easily customizable, CouchCMS provides an elegant foundation for building content-driven websites and applications.

What makes CouchCMS special is its developer-first approach. Rather than imposing rigid structures, CouchCMS gives you the freedom to define your content models, customize templates, and extend functionality through a clean, intuitive API. Whether you’re building a corporate website, blog, portfolio, or content-heavy application, CouchCMS adapts to your needs rather than forcing you to adapt to it.

Core Strengths of CouchCMS:

Lightweight Architecture: Minimal footprint with no unnecessary bloat. Fast installation, quick deployment, and efficient resource usage make CouchCMS ideal for small to medium-sized projects. The lean codebase is easy to understand and modify.

Developer-Friendly Design: Built for developers by developers. Clear, well-documented code makes it straightforward to understand the system, extend functionality, and integrate with external tools. No steep learning curve required.

Flexible Content Modeling: Define custom content types that match your exact needs. Create fields, set relationships, and build content hierarchies without touching code. The flexible admin interface adapts to your content structure.

Headless CMS Capabilities: Use CouchCMS as a headless CMS to serve content via API to multiple frontends. Build mobile apps, single-page applications, or static site generators on top of your content.

Template Engine: Powerful templating system for rendering your content. Use loops, conditionals, and custom tags to build complex page layouts without writing PHP.

User Management: Built-in user roles and permissions ensure your team members only access content they’re authorized to modify. Support multiple editors, contributors, and administrators.

File Management: Upload and organize media files directly from the admin interface. Automatic thumbnail generation and image optimization keep your site fast.

Search and Filtering: Full-text search capabilities help editors find content quickly. Advanced filtering makes it easy to navigate large content libraries.

Version Control: Track changes to your content with revision history. Revert to previous versions if needed, keeping an audit trail of all modifications.

Caching and Performance: Built-in caching mechanisms keep your site fast even under heavy traffic. Support for page caching and query optimization ensures excellent performance.

Extensibility: Add custom functionality through plugins and extensions. Hook into the system lifecycle and build features tailored to your specific needs.

Open Source and Community-Driven: Community contributions and open development mean CouchCMS continuously improves. Use the source code, audit for security, and contribute improvements back.

Whether you’re building your first website, managing content for a complex digital property, or creating a headless CMS for multiple channels, CouchCMS provides the flexibility and simplicity you need.

This guide walks you through deploying CouchCMS on Klutch.sh. You’ll learn how to configure a lightweight PHP-based CMS with persistent storage for your content and media files, set up authentication and user management, enable search functionality, optimize performance, and troubleshoot common issues in production.

Prerequisites

Before deploying CouchCMS to Klutch.sh, ensure you have:

A Klutch.sh account with dashboard access
A GitHub account for repository hosting
Docker installed locally for testing (optional but recommended)
Basic understanding of PHP and web applications
Familiarity with content management concepts
Knowledge of database administration
A domain name for your CouchCMS site (required for production use)
Understanding of web server configuration

Understanding CouchCMS Architecture

Technology Stack

CouchCMS is built on proven, straightforward technologies:

Core Platform:

PHP 7.4+ for server-side logic and content management
SQLite or MySQL/MariaDB for data persistence
Apache or Nginx web server
JavaScript for interactive admin interface features

Key Components:

Content management system for creating and managing pages and posts
Admin dashboard for content editing and site configuration
Template engine for rendering dynamic pages
User authentication system with role-based access
File management system for uploads and media
Search functionality for content discovery
Cache layer for performance optimization

Features:

Custom field types for flexible content modeling
Repeatable fields for dynamic content
Relationships between content items
Content versioning and revision history
User roles and permissions
Template inheritance and reusability
API for headless CMS use cases
Admin panel customization

Core Components

Web Server: Apache or Nginx serving PHP requests

PHP Application: CouchCMS application handling content operations and API requests

Database: SQLite (file-based) or MySQL for content storage

File System: Persistent storage for uploaded media and assets

Admin Interface: Web-based dashboard for content management

Template Engine: System for rendering pages with dynamic content

Installation and Setup

Step 1: Create Your Project Directory

Start with a dedicated directory for your CouchCMS deployment:

mkdir couchcms-deployment
cd couchcms-deployment
git init

Your project structure will look like:

couchcms-deployment/
├── Dockerfile
├── .env.example
├── .dockerignore
├── .gitignore
├── docker-compose.yml
├── couch/
│   ├── config.php
│   └── (CouchCMS installation)
├── uploads/
│   └── (user-uploaded media)
└── templates/
    └── (custom templates)

Step 2: Create the Dockerfile

Create a Dockerfile for a production-ready CouchCMS deployment:

# PHP with Apache base image
FROM php:8.2-apache-alpine

# Install required PHP extensions
RUN apk add --no-cache \
    mysql-client \
    curl \
    wget \
    bash \
    dumb-init

# Enable Apache modules
RUN a2enmod rewrite \
    && a2enmod headers

# Install PHP extensions
RUN docker-php-ext-install -j$(nproc) \
    pdo_mysql \
    pdo_sqlite

# Create non-root user
RUN addgroup -g 1000 www && \
    adduser -u 1000 -G www -s /sbin/nologin -D www

# Set working directory
WORKDIR /var/www/html

# Copy application files
COPY --chown=www:www . .

# Create necessary directories
RUN mkdir -p uploads cache logs && \
    chown -R www:www /var/www/html && \
    chmod -R 755 uploads cache logs

# Configure Apache
RUN sed -i 's|DocumentRoot /var/www/html|DocumentRoot /var/www/html|g' /etc/apache2/sites-enabled/000-default.conf

# Expose HTTP port
EXPOSE 80

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

# Use dumb-init for proper signal handling
ENTRYPOINT ["/usr/bin/dumb-init", "--"]

# Start Apache
CMD ["apache2-foreground"]

Step 3: Create Environment Configuration

Create a .env.example file with necessary CouchCMS configuration:

# CouchCMS Configuration

# Application Settings
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example-app.klutch.sh

# Database Configuration
DB_TYPE=mysql
DB_HOST=db
DB_PORT=3306
DB_NAME=couchcms
DB_USER=couchcms
DB_PASSWORD=your_secure_password

# PHP Configuration
PHP_MEMORY_LIMIT=256M
PHP_MAX_UPLOAD_SIZE=100M
PHP_MAX_EXECUTION_TIME=300

# Admin Configuration
ADMIN_PATH=/admin

# Security
APP_KEY=your_application_key_here
CSRF_ENABLED=true

# Email Configuration (optional)
MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=587
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_FROM=noreply@example-app.klutch.sh

# Cache Configuration
CACHE_DRIVER=file
CACHE_PATH=/var/www/html/cache

# File Upload Settings
UPLOAD_PATH=/var/www/html/uploads
MAX_UPLOAD_SIZE=104857600

Step 4: Create Apache Configuration

Create a .htaccess file for URL rewriting:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # Prevent direct access to sensitive files
    RewriteRule ^\.env$ - [F]
    RewriteRule ^config\.php$ - [F]
    RewriteRule ^\.git/ - [F]

    # Skip rewriting for real files and directories
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    # Redirect all requests to index.php
    RewriteRule ^(.*)$ index.php?/$1 [QSA,L]
</IfModule>

<IfModule !mod_rewrite.c>
    <IfModule mod_php.c>
        php_flag magic_quotes_gpc Off
        php_flag register_globals Off
        php_flag short_open_tag On
    </IfModule>
</IfModule>

Step 5: Create .dockerignore File

Create a .dockerignore to keep the image lean:

.git
.gitignore
.dockerignore
.env
.env.*
node_modules
npm-debug.log
yarn-error.log
README.md
.vscode
.idea
*.log
dist
build
coverage
.DS_Store
.git/
.env.local

Step 6: Create .gitignore File

Create a .gitignore to prevent committing sensitive files:

# Environment variables
.env
.env.local
.env.*.local

# Sensitive directories
uploads/*
!uploads/.gitkeep
cache/*
!cache/.gitkeep
logs/*
!logs/.gitkeep

# Dependencies
node_modules
vendor

# IDE
.vscode
.idea
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Temporary files
*.tmp
*.temp

Step 7: Create docker-compose.yml for Local Testing

Create a docker-compose.yml for local development:

version: '3.8'

services:
  db:
    image: mysql:8.0-alpine
    container_name: couchcms-db
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: couchcms
      MYSQL_USER: couchcms
      MYSQL_PASSWORD: couchcms_password
    ports:
      - "3306:3306"
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    build: .
    container_name: couchcms-app
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_HOST: db
      DB_USER: couchcms
      DB_PASSWORD: couchcms_password
      DB_NAME: couchcms
      APP_URL: http://localhost:8000
    ports:
      - "8000:80"
    volumes:
      - ./uploads:/var/www/html/uploads
      - ./cache:/var/www/html/cache
      - ./logs:/var/www/html/logs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  db-data:

Step 8: Create package.json

Create a package.json for dependency management:

{
  "name": "couchcms-deployment",
  "version": "1.0.0",
  "description": "CouchCMS content management system deployment on Klutch.sh",
  "keywords": [
    "couchcms",
    "cms",
    "content-management",
    "php",
    "headless-cms"
  ],
  "author": "Your Name",
  "license": "ISC"
}

Step 9: Initialize Git Repository

Set up your Git repository for deployment:

git add .
git commit -m "Initial CouchCMS deployment setup"
git branch -M main
git remote add origin https://github.com/yourusername/couchcms-deployment.git
git push -u origin main

Step 10: Download and Configure CouchCMS

Download CouchCMS and place it in your project’s couch/ directory, then configure:

# Download CouchCMS from https://www.couchcms.com/
# Extract and place in couch/ directory
# Edit couch/config.php with your database and admin settings

Step 11: Deploy to Klutch.sh

You’re ready to deploy. Follow these steps in the Klutch.sh dashboard:

Log in to klutch.sh/app and access your dashboard
Click "New" and select "Application" to create a new app deployment
Choose GitHub as your git source and select your CouchCMS repository
Select the main branch for automatic deployments
Select HTTP as the traffic type (CouchCMS is a web application)
Set the internal port to 80 (where Apache listens)
Add environment variables from your .env.example file:
- APP_URL - Set to your domain (e.g., https://example-app.klutch.sh)
- DB_HOST - Database host address
- DB_USER - Database user
- DB_PASSWORD - Strong database password
- DB_NAME - Database name (couchcms)
- PHP_MEMORY_LIMIT - Memory allocation (256M recommended)
- MAIL settings - For email notifications
Add persistent volumes for data persistence:
- Mount path: /var/www/html/uploads - Size: 50GB (for media files)
- Mount path: /var/www/html/cache - Size: 10GB (for cache files)
- Mount path: /var/www/html/logs - Size: 5GB (for application logs)
Review your configuration and click "Deploy"
Wait for the build and deployment to complete (typically 3-5 minutes)
Access your CouchCMS instance at the provided URL
Log in with your admin credentials and configure your site
Create content types and begin managing your content
Set up custom domain if desired by adding CNAME record

Getting Started with CouchCMS

Accessing the Admin Interface

Once deployed, access the admin dashboard at:

https://example-app.klutch.sh/admin

Creating Your First Content Type

Define a custom content type for your blog posts:

// Example: Creating a blog post content type
// In the CouchCMS admin interface, create a new type "blog"
// with these fields:
// - Title (text)
// - Content (textarea/WYSIWYG)
// - Author (text)
// - Published Date (date)
// - Category (select)
// - Featured Image (file)
// - Tags (repeatable)

Using the Template Engine

Create a template to display your blog posts:

<cms:template title="Blog Posts">
  <div class="blog-list">
    <cms:pages paginate='10'>
      <div class="post">
        <h2><cms:show k_page_title/></h2>
        <p class="meta">By <cms:show author/> on <cms:date k_page_date format='j M Y'/></p>
        <div class="content">
          <cms:show k_page_content/>
        </div>
        <a href="<cms:show k_page_link/>">Read More</a>
      </div>
    </cms:pages>
  </div>
</cms:template>

Working with Repeatable Fields

Create dynamic content with repeatable fields:

<cms:if k_count>
  <div class="carousel">
    <cms:repeatable 'slides'>
      <div class="slide">
        <img src="<cms:show slide_image/>" alt="<cms:show slide_title/>">
        <h3><cms:show slide_title/></h3>
        <p><cms:show slide_description/></p>
      </div>
    </cms:repeatable>
  </div>
</cms:if>

API Usage Examples

Use CouchCMS as a headless CMS via the API:

JavaScript/Node.js - Fetching Content:

async function fetchBlogPosts() {
  const response = await fetch('https://example-app.klutch.sh/api/pages?type=blog', {
    headers: {
      'Accept': 'application/json'
    }
  });

  const data = await response.json();
  return data.items;
}

// Usage
fetchBlogPosts().then(posts => {
  console.log('Blog posts:', posts);
});

Python - Content Integration:

import requests

COUCHCMS_URL = 'https://example-app.klutch.sh'

# Fetch pages of a specific type
response = requests.get(
    f'{COUCHCMS_URL}/api/pages',
    params={'type': 'blog'}
)

posts = response.json()['items']
for post in posts:
    print(f"Title: {post['title']}")
    print(f"Published: {post['publishedDate']}")

cURL - Direct API Access:

# Get all blog posts
curl -H "Accept: application/json" \
  https://example-app.klutch.sh/api/pages?type=blog

# Get a specific page
curl -H "Accept: application/json" \
  https://example-app.klutch.sh/api/pages/my-blog-post

Performance Optimization

Database Optimization

Keep your MySQL database performing efficiently:

Query Optimization: Profile slow queries and add indexes to frequently searched fields
Connection Pooling: Use connection pooling for better resource utilization
Regular Maintenance: Schedule OPTIMIZE and ANALYZE operations
Backup Strategy: Implement regular automated backups
Archive Old Content: Move archived content to separate tables

Caching Strategy

Implement effective caching:

Page Caching: Cache rendered pages for static content
Query Caching: Cache database query results
Fragment Caching: Cache template fragments that don’t change frequently
HTTP Caching: Set appropriate cache headers for browser caching
Cache Invalidation: Automatically clear cache when content changes

File and Media Optimization

Optimize media delivery:

Image Optimization: Automatically resize and compress images on upload
Lazy Loading: Load images only when needed
CDN Integration: Serve media from a CDN for faster delivery
Format Conversion: Convert images to modern formats (WebP)
Storage Management: Monitor and clean up unused files

Security Best Practices

Authentication and Access Control

Protect your CMS:

Strong Passwords: Enforce strong password requirements for all admin users
Two-Factor Authentication: Enable 2FA for admin accounts if available
User Roles: Assign appropriate roles and permissions to team members
Session Management: Set secure session timeouts
Audit Logging: Monitor admin activities and access logs

Data Protection

Safeguard your content:

HTTPS Only: Always use HTTPS for all communication
Database Encryption: Enable encryption for sensitive database fields
Regular Backups: Automated daily backups with test restoration
Input Validation: Validate all user input to prevent injection attacks
File Uploads: Restrict file types and validate uploaded files

Infrastructure Security

Secure your deployment:

Regular Updates: Apply security patches promptly
Dependency Updates: Keep PHP and extensions current
Remove Admin Path: Change default /admin path to custom URL
Firewall Rules: Restrict access to admin functions
Monitor Logs: Review security logs regularly

Troubleshooting

Application Won’t Start

If your CouchCMS instance isn’t accessible:

Check Logs: View deployment logs in Klutch.sh dashboard
Database Connection: Verify MySQL is running and accessible
Environment Variables: Confirm all required variables are set
File Permissions: Ensure proper permissions on uploads and cache directories
PHP Extensions: Verify required PHP extensions are loaded

Solution: Review error logs and verify database credentials. Restart the container if needed.

Database Connection Errors

MySQL connection issues prevent CouchCMS from functioning:

Connection String: Verify database host, user, and password
Database Exists: Ensure the couchcms database exists
User Permissions: Verify user has all necessary permissions
Network Access: Check that the container can reach the database
Port Configuration: Verify port 3306 is accessible

Solution: Test the connection manually. Verify credentials match environment variables.

Content Not Saving

Changes aren’t persisting to the database:

Database Permissions: Check user permissions for INSERT/UPDATE operations
Database Connectivity: Verify connection isn’t dropping
Disk Space: Ensure persistent volume has sufficient space
File Permissions: Check upload directory permissions
Timeout Issues: Increase PHP timeout if large operations are slow

Solution: Check database logs for errors. Verify permissions on all directories.

Slow Page Loading

Performance degradation affects user experience:

Database Queries: Check for slow queries in database logs
Caching: Verify caching is enabled and working
File Size: Monitor uploaded file sizes and optimize images
Memory Usage: Check PHP memory utilization
Query Count: Reduce number of queries on template pages

Solution: Enable query caching. Optimize images on upload. Implement page caching.

Upload Issues

File uploads aren’t working:

Upload Directory: Verify /var/www/html/uploads permissions
File Size Limits: Check PHP max_upload_size and post_max_size
Disk Space: Ensure sufficient space in persistent volume
File Types: Verify file type restrictions allow your files
Permissions: Ensure web server user can write to upload directory

Solution: Check upload directory permissions (755 recommended). Verify PHP configuration limits.

Memory or Disk Space Issues

Performance problems related to resource constraints:

Memory Limit: Increase PHP_MEMORY_LIMIT if needed
Disk Usage: Monitor persistent volume usage
Cache Cleanup: Clear old cache files regularly
Old Revisions: Archive or delete old content revisions
Log Files: Implement log rotation and cleanup

Solution: Increase resource allocations. Implement cleanup scripts for cache and logs.

Custom Domain Setup

To use your own domain instead of example-app.klutch.sh:

Step 1: Add Domain in Klutch.sh

In the Klutch.sh dashboard, go to your application settings and add your custom domain.

Step 2: Create DNS CNAME Record

In your domain registrar’s DNS settings, create:

Domain: yourdomain.com
Type: CNAME
Value: example-app.klutch.sh

Step 3: Verify SSL Certificate

Klutch.sh automatically provisions SSL certificates, typically completing within minutes.

Step 4: Update Application Configuration

Update your CouchCMS environment variables:

APP_URL=https://yourdomain.com
MAIL_FROM=noreply@yourdomain.com

Restart your application for changes to take effect.

Production Best Practices

Regular Backups

Protect your content:

Automated Backups: Schedule daily database backups
Backup Verification: Test restoration procedures regularly
Off-Site Storage: Store backups in separate location
Retention Policy: Keep backups for at least 30 days
Disaster Recovery: Document recovery procedures

Monitoring and Maintenance

Stay informed about system health:

Uptime Monitoring: Use external monitoring services
Error Tracking: Monitor error logs and alerts
Performance Monitoring: Track page load times
Resource Monitoring: Alert on disk space and memory
Access Monitoring: Track admin activity

Content Management

Best practices for content operations:

Revision Management: Regularly clean up old revisions
Archive Old Content: Move archived content to separate sections
Media Cleanup: Remove unused uploaded files
Spam Prevention: Monitor and manage spam content
Backup Before Changes: Backup before major updates

Security Maintenance

Keep your deployment secure:

Regular Updates: Apply security patches promptly
Access Reviews: Regularly review user permissions
Password Updates: Encourage regular password changes
Security Audits: Conduct periodic security reviews
Compliance: Ensure compliance with data regulations

Conclusion

Deploying CouchCMS on Klutch.sh provides a lightweight, flexible content management system perfect for websites and content-driven applications. The combination of simplicity, developer-friendly design, and powerful features makes CouchCMS ideal for teams that value clean code and straightforward deployment.

For more information about CouchCMS, visit the official CouchCMS website and CouchCMS documentation. Check out the CouchCMS GitHub repository for source code and community contributions.

Klutch.sh handles the infrastructure, letting you focus on creating and managing content. With persistent storage for your uploads, automatic scaling, and integrated monitoring, you have everything needed for a production-ready CMS deployment.

Start simple with basic pages and blog posts, then expand with custom content types and advanced features as your needs grow. CouchCMS scales from simple websites to complex content platforms without requiring architectural changes.

Happy managing!