Skip to content
Klutch.sh Docs

Deploying a WordPress App

Introduction

WordPress is the world’s most popular content management system (CMS), powering over 43% of all websites on the internet. Since its launch in 2003, WordPress has evolved from a simple blogging platform into a powerful, versatile CMS capable of building anything from personal blogs to enterprise websites, online stores, membership sites, and complex web applications.

Built with PHP and MySQL, WordPress offers an intuitive admin interface, thousands of free and premium themes, over 60,000 plugins extending functionality, a robust REST API, built-in SEO optimization, multi-language support, and a thriving global community of developers and users. Whether you’re launching a personal blog, building a business website, or creating a custom web application, WordPress provides the flexibility and tools you need.

Deploying WordPress on Klutch.sh gives you automatic Docker detection, persistent storage for media files and custom code, seamless MySQL database integration, automatic HTTPS certificates, custom domain support, and simplified deployment workflow. This comprehensive guide walks you through deploying WordPress with production-ready configuration, including database setup, persistent volume management, security best practices, and performance optimization.

Why Deploy WordPress on Klutch.sh?

  • Simplified Infrastructure: Launch your WordPress site without managing complex server configurations
  • Automatic HTTPS: Built-in SSL certificates for secure connections
  • Persistent Storage: Reliable volume storage for uploads, themes, and plugins
  • Custom Domains: Use your own domain for professional branding
  • Database Integration: Easy connection to MySQL or MariaDB databases
  • Environment Variables: Secure configuration management through the dashboard
  • Easy Scaling: Adjust resources as your traffic grows
  • Zero Downtime Updates: Deploy updates without interrupting your site
  • Container Benefits: Isolated, reproducible environment with version control
  • GitHub Integration: Automated deployments from your repository
  • Global CDN Ready: Easy integration with CDN services for optimal performance

Prerequisites

Before you begin, ensure you have:

Understanding WordPress Architecture

WordPress is built on a classic LAMP stack architecture:

Core Components:

  • PHP Application: WordPress core written in PHP (8.0+ recommended)
  • Web Server: Apache or Nginx serving the application
  • MySQL Database: Stores posts, pages, users, settings, and all content
  • File System: Stores themes, plugins, uploads, and configuration
  • wp-config.php: Main configuration file with database credentials
  • wp-content: Directory containing themes, plugins, and uploads

Default Structure:

/var/www/html/
├── index.php           # Main entry point
├── wp-config.php       # Configuration file
├── wp-admin/           # Admin dashboard
├── wp-includes/        # Core WordPress files
├── wp-content/         # User content (persist this!)
│   ├── themes/         # Theme files
│   ├── plugins/        # Plugin files
│   ├── uploads/        # Media library
│   └── languages/      # Translation files
├── .htaccess           # Apache rewrite rules
└── xmlrpc.php          # XML-RPC endpoint

Key Features:

  • WYSIWYG visual editor (Gutenberg block editor)
  • Media library for image/file management
  • User roles and permissions system
  • Built-in commenting system
  • Custom post types and taxonomies
  • Widgets and menus for site structure
  • Theme customizer for visual changes
  • Plugin architecture for extending functionality
  • REST API for headless CMS usage
  • Multisite capability for network installations
  • Built-in SEO features and permalink management
  • Automatic updates for core, themes, and plugins
  • Import/export tools
  • Built-in search functionality

When deploying on Klutch.sh, we’ll containerize WordPress with Apache/PHP and connect it to a separately deployed MySQL instance for optimal performance and easier maintenance.

Preparing Your Repository

Step 1: Create Project Directory

Create a new directory for your WordPress deployment:

Terminal window
mkdir wordpress-deploy
cd wordpress-deploy
git init

Step 2: Understanding WordPress Requirements

WordPress requires the following to run successfully:

  • PHP: Version 7.4 or higher (8.0+ recommended)
  • Web Server: Apache or Nginx
  • Database: MySQL 5.7+ or MariaDB 10.3+
  • PHP Extensions: mysqli, curl, gd, mbstring, xml, zip, openssl
  • Storage: Persistent storage for wp-content directory
  • Memory: Minimum 256MB PHP memory limit (512MB recommended)

Deploying with a Dockerfile

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it to build your application. This approach provides reproducible builds, full control over dependencies, and consistency across environments.

Sample Dockerfile for WordPress

Create a Dockerfile in your repository root with the following content:

FROM wordpress:6.6-php8.2-apache


# Install additional PHP extensions if needed
RUN apt-get update && apt-get install -y \
    libzip-dev \
    zip \
    unzip \
    && docker-php-ext-install zip \
    && rm -rf /var/lib/apt/lists/*


# Configure PHP settings
RUN echo "upload_max_filesize = 64M" > /usr/local/etc/php/conf.d/uploads.ini \
    && echo "post_max_size = 64M" >> /usr/local/etc/php/conf.d/uploads.ini \
    && echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/uploads.ini \
    && echo "max_execution_time = 300" >> /usr/local/etc/php/conf.d/uploads.ini


# Enable Apache modules
RUN a2enmod rewrite expires headers


# Set working directory
WORKDIR /var/www/html


# WordPress runs on port 80 internally
EXPOSE 80


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


# The base image already has an entrypoint configured
# This starts Apache with WordPress

This Dockerfile uses the official wordpress:6.6-php8.2-apache image, which includes:

  • WordPress core files pre-installed
  • Apache web server configured for WordPress
  • PHP 8.2 with necessary extensions
  • Automatic wp-config.php generation from environment variables
  • Support for WordPress CLI (wp-cli)

Alternative: Custom WordPress Installation

If you need more control or want to customize the WordPress installation, use this alternative Dockerfile:

FROM php:8.2-apache


# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    libonig-dev \
    libxml2-dev \
    libwebp-dev \
    zip \
    unzip \
    curl \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) \
        gd \
        mysqli \
        pdo_mysql \
        zip \
        opcache \
        exif \
        mbstring \
    && rm -rf /var/lib/apt/lists/*


# Configure PHP for WordPress
RUN { \
        echo 'upload_max_filesize = 64M'; \
        echo 'post_max_size = 64M'; \
        echo 'memory_limit = 512M'; \
        echo 'max_execution_time = 300'; \
        echo 'max_input_time = 300'; \
    } > /usr/local/etc/php/conf.d/wordpress.ini


# Configure OPcache for better performance
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=2'; \
        echo 'opcache.fast_shutdown=1'; \
    } > /usr/local/etc/php/conf.d/opcache.ini


# Enable Apache modules
RUN a2enmod rewrite expires headers deflate


# Download and install WordPress
ENV WORDPRESS_VERSION 6.6
RUN curl -o wordpress.tar.gz -fSL "https://wordpress.org/wordpress-${WORDPRESS_VERSION}.tar.gz" \
    && tar -xzf wordpress.tar.gz -C /var/www/html --strip-components=1 \
    && rm wordpress.tar.gz \
    && chown -R www-data:www-data /var/www/html


# Set working directory
WORKDIR /var/www/html


EXPOSE 80


CMD ["apache2-foreground"]

Custom wp-config.php (Optional)

For advanced configurations, you can create a custom wp-config.php. However, the official WordPress Docker image automatically generates this from environment variables, which is recommended for containerized deployments.

Step-by-Step Deployment on Klutch.sh

1. Push Your Repository to GitHub

    1. Commit your Dockerfile to your repository:

      Terminal window
      git add Dockerfile
      git commit -m "Add WordPress Dockerfile for Klutch.sh deployment"
      git push origin main

2. Create a New App on Klutch.sh

    1. Log in to the Klutch.sh dashboard

    2. Create a new project or select an existing one

    3. Create a new app and configure it:

      • Repository: Select your WordPress GitHub repository
      • Branch: Choose the branch to deploy (e.g., main or production)
      • Traffic Type: Select HTTP (WordPress is a web application)
      • Internal Port: Set to 80 (Apache’s default port)

3. Configure Persistent Volumes

WordPress requires persistent storage for themes, plugins, and uploaded media. Set up a volume in your app configuration:

    1. In your app settings, navigate to the Volumes section

    2. Add a volume with the following configuration:

      • Mount Path: /var/www/html/wp-content
      • Size: Start with 10GB, scale based on expected media usage

Storage Recommendations by Site Type:

  • Personal Blog: 5-10GB (minimal media, few plugins)
  • Business Website: 10-25GB (moderate media, several plugins/themes)
  • Media-Heavy Site: 50-100GB (photography, video content)
  • E-commerce Store: 25-100GB (product images, multiple plugins)
  • Enterprise/Multi-author: 100GB+ (extensive content, many plugins)

Important: When configuring volumes on Klutch.sh, you only specify the mount path and size. The platform handles volume naming and management automatically.

4. Set Environment Variables

Configure the required environment variables for WordPress to connect to your database:

    1. In your app settings, navigate to the Environment Variables section

    2. Add the following required variables (mark sensitive values as secrets):

      Database Configuration:

      Terminal window
      # MySQL/MariaDB connection details
      WORDPRESS_DB_HOST=mysql-app.klutch.sh:8000
      WORDPRESS_DB_NAME=wordpress
      WORDPRESS_DB_USER=wordpress_user
      WORDPRESS_DB_PASSWORD=your-secure-password

      WordPress Configuration:

      Terminal window
      # Table prefix (default: wp_)
      WORDPRESS_TABLE_PREFIX=wp_
      

      # Debug mode (set to false in production)
      WORDPRESS_DEBUG=false
      

      # Memory limits
      WP_MEMORY_LIMIT=256M
      WP_MAX_MEMORY_LIMIT=512M

      Optional - Advanced Configuration:

      Terminal window
      # Disable file editing from admin panel (security)
      WORDPRESS_CONFIG_EXTRA="define('DISALLOW_FILE_EDIT', true);"
      

      # Force SSL admin (if using custom domain with HTTPS)
      FORCE_SSL_ADMIN=true
      

      # Automatic core updates
      AUTOMATIC_UPDATER_DISABLED=false

Security Note: Always mark WORDPRESS_DB_PASSWORD and any API keys as secrets in Klutch.sh to prevent them from appearing in logs or being exposed.

5. Configure Additional Settings

    1. Region: Choose a region closest to your target audience for optimal performance

    2. Compute: Select an instance size based on your expected traffic:

      • Small (1 CPU, 1GB RAM): Personal blog or low-traffic site (up to 1,000 monthly visitors)
      • Medium (2 CPU, 2GB RAM): Small business site (1,000-10,000 monthly visitors)
      • Large (4 CPU, 4GB RAM): Medium traffic or e-commerce (10,000-50,000 monthly visitors)
      • XLarge (8 CPU, 8GB RAM): High-traffic or resource-intensive sites (50,000+ monthly visitors)

    3. Instances: Start with 1 instance (multiple instances require additional configuration for shared sessions and file storage)

6. Deploy Your Application

    1. Review your configuration settings

    2. Click “Create” to start the deployment

    3. Klutch.sh will:

      • Detect your Dockerfile automatically
      • Build your Docker image
      • Deploy the container with your configured volumes and environment variables
      • Route HTTP traffic to port 80 inside your container
      • Generate a public URL like example-app.klutch.sh

    4. Monitor the build and deployment progress in the dashboard

    5. Wait for the deployment to complete (initial deployment typically takes 2-5 minutes)

7. Complete WordPress Installation

    1. Once deployment is complete, visit your app URL (e.g., https://example-app.klutch.sh)

    2. Complete the WordPress installation wizard:

      • Language: Select your preferred language
      • Site Title: Enter your website name
      • Username: Create an admin username (avoid “admin” for security)
      • Password: Use a strong password (WordPress will suggest one)
      • Email: Enter your admin email address
      • Search Engine Visibility: Check this to discourage search engines during development

    3. Click “Install WordPress”

    4. Log in with your admin credentials

    5. You’re now ready to customize your site!

Database Setup and Configuration

WordPress requires MySQL or MariaDB for storing all content and configuration.

Deploy a MySQL database as a separate app on Klutch.sh:

    1. Create a new app with the MySQL Docker image
    2. Configure it with TCP traffic type (not HTTP)
    3. Set internal port to 5432 for PostgreSQL or 3306 for MySQL
    4. Set up persistent storage at /var/lib/mysql (minimum 10GB for MySQL)
    5. Configure environment variables for database credentials
    6. Note the app URL (e.g., mysql-app.klutch.sh)
    7. Use mysql-app.klutch.sh:8000 as your WORDPRESS_DB_HOST

See our MySQL deployment guide or MariaDB deployment guide for detailed instructions.

Option 2: Use a Managed Database Service

For production deployments with high availability requirements, consider managed database services:

These services provide automatic backups, point-in-time recovery, high availability, and simplified maintenance.

Database Initialization

WordPress will automatically create the necessary database tables on first installation. The initial database schema includes tables for:

  • Posts and pages
  • Users and user metadata
  • Comments
  • Options (site settings)
  • Taxonomy (categories and tags)
  • Links and navigation menus
  • Post metadata

Initial Database Size: Start with 5-10GB and monitor growth. Active sites can grow significantly over time with content and metadata.

Theme and Plugin Management

Installing Themes

Method 1: From WordPress Admin Dashboard

    1. Navigate to Appearance > Themes in the admin dashboard
    2. Click “Add New”
    3. Browse or search for themes
    4. Click “Install” then “Activate”

Method 2: Upload Custom Theme

    1. Navigate to Appearance > Themes > Add New > Upload Theme
    2. Choose your theme ZIP file
    3. Click “Install Now” then “Activate”

Method 3: Via Dockerfile (Recommended for Custom Themes)

Add to your Dockerfile:

FROM wordpress:6.6-php8.2-apache


# Copy custom theme
COPY ./themes/my-custom-theme /var/www/html/wp-content/themes/my-custom-theme


# Set proper permissions
RUN chown -R www-data:www-data /var/www/html/wp-content/themes


EXPOSE 80

Installing Plugins

Method 1: From WordPress Admin Dashboard

    1. Navigate to Plugins > Add New
    2. Browse or search for plugins
    3. Click “Install Now” then “Activate”

Method 2: Via Dockerfile (Recommended for Required Plugins)

Add to your Dockerfile:

FROM wordpress:6.6-php8.2-apache


# Install WordPress CLI
RUN curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar \
    && chmod +x wp-cli.phar \
    && mv wp-cli.phar /usr/local/bin/wp


# Install required plugins (run after WordPress is set up)
# This is typically done through a startup script
COPY install-plugins.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/install-plugins.sh


EXPOSE 80

install-plugins.sh:

#!/bin/bash
# Wait for WordPress to be ready
sleep 10


# Install and activate plugins
wp plugin install wordfence --activate --allow-root
wp plugin install wp-super-cache --activate --allow-root
wp plugin install contact-form-7 --activate --allow-root

Essential Plugins for Production

Security:

Performance:

SEO:

Backups:

Forms:

Content Management

Creating Posts and Pages

Posts are for blog content (news, articles) and appear in reverse chronological order:

    1. Navigate to Posts > Add New
    2. Enter title and content using the block editor
    3. Set categories and tags
    4. Configure excerpt and featured image
    5. Click “Publish”

Pages are for static content (About, Contact, Services):

    1. Navigate to Pages > Add New
    2. Enter title and content
    3. Choose page template (if your theme provides options)
    4. Set parent page if creating a hierarchy
    5. Click “Publish”

Media Management

Upload and manage images, videos, and documents:

    1. Navigate to Media > Library
    2. Click “Add New” to upload files
    3. Drag and drop multiple files
    4. Edit metadata (title, alt text, description)
    5. Organize with media folders (requires plugin)

Best Practices:

  • Optimize images before upload (use tools like TinyPNG)
  • Use descriptive filenames (helps with SEO)
  • Add alt text to all images (accessibility and SEO)
  • Recommended image sizes: max 2000px width, under 200KB
  • Use appropriate formats (JPEG for photos, PNG for graphics, WebP for modern browsers)

Create custom navigation menus:

    1. Navigate to Appearance > Menus
    2. Create a new menu or edit existing
    3. Add pages, posts, custom links, or categories
    4. Drag and drop to reorganize
    5. Create sub-menus by indenting items
    6. Assign menu to theme location (header, footer, etc.)
    7. Click “Save Menu”

Security Best Practices

Authentication and Access Control

    1. Strong Admin Credentials:

      • Use unique username (avoid “admin”)
      • Enable strong passwords (minimum 12 characters)
      • Change passwords regularly

    2. User Role Management:

      • Create users with appropriate roles (Administrator, Editor, Author, Contributor, Subscriber)
      • Grant least privileges necessary
      • Remove unused accounts

    3. Two-Factor Authentication:

    4. Limit Login Attempts:

WordPress Hardening

    1. Disable File Editing:

      Add to your environment variables:

      Terminal window
      WORDPRESS_CONFIG_EXTRA="define('DISALLOW_FILE_EDIT', true);"

    2. Hide WordPress Version:

      Add to functions.php in your theme:

      remove_action('wp_head', 'wp_generator');

    3. Disable XML-RPC (if not needed):

      Add to .htaccess:

      <Files xmlrpc.php>
        Order Allow,Deny
        Deny from all
      </Files>

    4. Protect wp-config.php:

      Add to .htaccess:

      <Files wp-config.php>
        Order Allow,Deny
        Deny from all
      </Files>

    5. Security Headers:

      Add to your Apache configuration or .htaccess:

      Header set X-Content-Type-Options "nosniff"
      Header set X-Frame-Options "SAMEORIGIN"
      Header set X-XSS-Protection "1; mode=block"
      Header set Referrer-Policy "strict-origin-when-cross-origin"

Regular Maintenance

    1. Keep WordPress Updated:

      • Enable automatic core updates
      • Update plugins and themes regularly
      • Test updates in staging environment first

    2. Install Security Plugin:

      • Use Wordfence or similar
      • Configure firewall rules
      • Enable malware scanning
      • Set up email alerts

    3. Regular Backups:

      • Database: Daily backups
      • Files (wp-content): Weekly backups
      • Store backups off-site
      • Test restore procedures

    4. Monitor Activity:

      • Install activity log plugin
      • Monitor failed login attempts
      • Review user activity
      • Check for suspicious files

Performance Optimization

Caching Strategy

    1. Page Caching:

      • Install WP Super Cache or W3 Total Cache
      • Enable page caching for logged-out users
      • Configure cache expiration (24 hours recommended)

    2. Object Caching:

      • Use Redis or Memcached for object caching
      • Install Redis Object Cache plugin
      • Configure persistent connection

    3. Opcode Caching:

      • Included in our Dockerfile with OPcache
      • Caches compiled PHP bytecode
      • Reduces server load significantly

Database Optimization

    1. Clean Up Database:

      • Install WP-Optimize plugin
      • Remove post revisions regularly
      • Delete spam comments
      • Clean transients and expired options

    2. Optimize Tables:

      OPTIMIZE TABLE wp_posts, wp_postmeta, wp_options;

    3. Limit Post Revisions:

      Add to wp-config.php via environment variables:

      Terminal window
      WORDPRESS_CONFIG_EXTRA="define('WP_POST_REVISIONS', 5);"

Content Delivery

    1. Image Optimization:

      • Install Imagify or ShortPixel
      • Enable automatic compression
      • Serve images in WebP format
      • Lazy load images below the fold

    2. CSS/JS Optimization:

      • Install Autoptimize plugin
      • Minify CSS and JavaScript
      • Combine files when possible
      • Defer non-critical CSS/JS

    3. CDN Integration:

      • Use Cloudflare, StackPath, or similar
      • Configure WordPress to use CDN URLs
      • Cache static assets globally
      • Enable Brotli compression

Performance Monitoring

    1. Monitor Page Speed:

      • Use Google PageSpeed Insights
      • Target 90+ score for mobile and desktop
      • Monitor Core Web Vitals

    2. Database Query Monitoring:

      • Install Query Monitor plugin
      • Identify slow queries
      • Optimize problematic queries

    3. Server Resource Usage:

      • Monitor CPU and memory usage in Klutch.sh dashboard
      • Scale resources if consistently high
      • Review error logs for issues

Backup and Disaster Recovery

Automated Backup Strategy

    1. Database Backups:

      Using UpdraftPlus or similar:

      • Schedule: Daily for database
      • Retention: 30 days
      • Storage: Remote (S3, Google Drive, Dropbox)

    2. File Backups:

      • Schedule: Weekly for wp-content
      • Retention: 4 weeks
      • Include themes, plugins, and uploads

    3. Backup Script Example:

      #!/bin/bash
      # Database backup
      mysqldump -h mysql-app.klutch.sh -P 8000 -u wordpress_user -p'password' wordpress > backup-$(date +%Y%m%d).sql
      

      # Compress and upload to S3
      gzip backup-$(date +%Y%m%d).sql
      aws s3 cp backup-$(date +%Y%m%d).sql.gz s3://your-bucket/wordpress-backups/
      

      # Clean up old backups (keep 30 days)
      find . -name "backup-*.sql.gz" -mtime +30 -delete

Disaster Recovery Plan

    1. Document Your Configuration:

      • List all active plugins and themes
      • Document custom code modifications
      • Save copies of configuration files
      • Keep environment variables documented

    2. Test Restore Procedures:

      • Practice restoring from backup monthly
      • Verify database integrity
      • Test site functionality after restore

    3. Emergency Contacts:

      • Maintain list of key personnel
      • Document hosting provider support contacts
      • Keep WordPress community resources handy

Troubleshooting Common Issues

Site Not Loading

Problem: White screen or 500 error after deployment

Solutions:

    1. Check database connection:

      • Verify WORDPRESS_DB_HOST includes port (:8000)
      • Test database connectivity
      • Confirm credentials are correct

    2. Review container logs in Klutch.sh dashboard:

      Terminal window
      # Look for PHP errors
      tail -f /var/log/apache2/error.log

    3. Increase PHP memory limit:

      Terminal window
      WP_MEMORY_LIMIT=512M

    4. Check file permissions:

      Terminal window
      chown -R www-data:www-data /var/www/html

Upload Errors

Problem: “Unable to create directory” or upload fails

Solutions:

    1. Verify persistent volume is mounted at /var/www/html/wp-content

    2. Check disk space:

      • Monitor volume usage in Klutch.sh dashboard
      • Increase volume size if near capacity

    3. Verify file size limits in Dockerfile:

      RUN echo "upload_max_filesize = 64M" > /usr/local/etc/php/conf.d/uploads.ini \
          && echo "post_max_size = 64M" >> /usr/local/etc/php/conf.d/uploads.ini

    4. Check file permissions:

      Terminal window
      chmod 755 /var/www/html/wp-content/uploads

Plugin/Theme Installation Fails

Problem: Cannot install or update plugins/themes

Solutions:

    1. Verify write permissions to wp-content

    2. Check available disk space

    3. Disable conflicting plugins

    4. Install via WP-CLI as workaround:

      Terminal window
      wp plugin install plugin-name --activate

Performance Issues

Problem: Slow page load times

Solutions:

    1. Enable Caching:

      • Install and configure WP Super Cache
      • Enable browser caching in .htaccess

    2. Optimize Database:

      • Run WP-Optimize to clean database
      • Remove unused plugins and themes

    3. Check Resource Usage:

      • Review CPU/memory in Klutch.sh dashboard
      • Scale to larger instance if needed

    4. Analyze Slow Queries:

      • Install Query Monitor plugin
      • Identify and optimize slow database queries

    5. Enable CDN:

      • Use Cloudflare or similar
      • Offload static assets

Database Connection Errors

Problem: “Error establishing database connection”

Solutions:

    1. Verify environment variables:

      Terminal window
      WORDPRESS_DB_HOST=mysql-app.klutch.sh:8000
      WORDPRESS_DB_NAME=wordpress
      WORDPRESS_DB_USER=wordpress_user
      WORDPRESS_DB_PASSWORD=correct-password

    2. Test database connectivity:

      Terminal window
      mysql -h mysql-app.klutch.sh -P 8000 -u wordpress_user -p

    3. Check MySQL service status

    4. Verify firewall rules allow connection between apps

Problem: Posts/pages show 404 errors

Solutions:

    1. Ensure mod_rewrite is enabled (included in our Dockerfile)

    2. Regenerate permalinks:

      • Go to Settings > Permalinks
      • Click “Save Changes” without changing anything

    3. Check .htaccess file exists and is writable:

      # BEGIN WordPress
      <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteBase /
      RewriteRule ^index\.php$ - [L]
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule . /index.php [L]
      </IfModule>
      # END WordPress

Production Deployment Checklist

Before launching your WordPress site:

  • MySQL database deployed with automated backups
  • Persistent volume configured at /var/www/html/wp-content with adequate size
  • All environment variables set (especially database credentials marked as secrets)
  • Strong admin username and password configured
  • Unnecessary default plugins removed
  • Security plugin installed and configured (Wordfence or similar)
  • SSL/HTTPS enabled (automatic with Klutch.sh)
  • Custom domain configured (optional)
  • Permalink structure set (e.g., /%postname%/)
  • XML-RPC disabled (if not needed)
  • File editing disabled in admin panel
  • Two-factor authentication enabled for admin accounts
  • Backup plugin installed and configured
  • Caching plugin installed and configured
  • Image optimization plugin installed
  • SEO plugin installed and configured (Yoast SEO)
  • Google Analytics or similar tracking installed
  • Contact forms tested
  • Email functionality tested
  • Performance optimized (page speed 90+ score)
  • Mobile responsiveness verified
  • Browser compatibility tested
  • Search functionality tested
  • 404 page customized
  • Robots.txt configured
  • Sitemap generated and submitted to search engines
  • Social media meta tags configured
  • Legal pages created (Privacy Policy, Terms of Service)
  • Staging environment created for testing updates
  • Monitoring and uptime alerts configured
  • Documentation created for site maintenance

Advanced Configuration

Custom Domain Setup

To use a custom domain with your WordPress deployment:

    1. Configure your custom domain in the Klutch.sh dashboard (see Custom Domains Guide)

    2. Update your DNS records to point to your Klutch.sh app

    3. Update WordPress site URL:

      • Navigate to Settings > General

      • Update WordPress Address (URL) and Site Address (URL)

      • Or add to environment variables:

        Terminal window
        WORDPRESS_CONFIG_EXTRA="define('WP_HOME', 'https://yourdomain.com'); define('WP_SITEURL', 'https://yourdomain.com');"

    4. Klutch.sh automatically manages TLS certificates for your domain

    5. Set up 301 redirects from old domain if migrating

WordPress Multisite

To enable WordPress Multisite for managing multiple sites from one installation:

    1. Add to environment variables:

      Terminal window
      WORDPRESS_CONFIG_EXTRA="define('WP_ALLOW_MULTISITE', true);"

    2. After enabling, navigate to Tools > Network Setup

    3. Choose subdomain or subdirectory installation

    4. Update environment variables with generated configuration

    5. Configure wildcard DNS for subdomains (if using subdomain multisite)

WooCommerce for E-commerce

To add e-commerce functionality to WordPress:

    1. Install WooCommerce plugin:

      Terminal window
      wp plugin install woocommerce --activate

    2. Run the setup wizard to configure:

      • Store details
      • Payment gateways (Stripe, PayPal)
      • Shipping options
      • Tax rates

    3. Configure persistent storage for product images

    4. Set up automated backups for order data

    5. Consider upgrading compute resources for better performance

See our WooCommerce deployment guide for detailed e-commerce setup.

Headless WordPress

Use WordPress as a headless CMS with the REST API:

    1. Enable REST API (enabled by default)

    2. Install JWT Authentication plugin:

      Terminal window
      wp plugin install jwt-authentication-for-wp-rest-api --activate

    3. Configure CORS headers in .htaccess:

      Header set Access-Control-Allow-Origin "*"
      Header set Access-Control-Allow-Methods "GET, POST, OPTIONS, DELETE, PUT"

    4. Access content via REST API:

      Terminal window
      curl https://example-app.klutch.sh/wp-json/wp/v2/posts

    5. Build frontend with React, Vue, or Next.js consuming the WordPress API

Integration Examples

Google Analytics Integration

Add tracking to your WordPress site:

Method 1: Using Plugin

    1. Install MonsterInsights or Site Kit by Google
    2. Connect to your Google Analytics account
    3. Configure tracking options

Method 2: Manual Integration

Add to your theme’s header.php:

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>

Social Media Integration

Add social sharing and feeds:

    1. Install social sharing plugin like Social Warfare

    2. Configure social meta tags (Open Graph, Twitter Cards):

      • Install Yoast SEO (includes social meta)
      • Configure social profiles
      • Set default social images

    3. Embed social feeds:

Email Marketing Integration

Connect WordPress to email marketing platforms:

Mailchimp:

    1. Install MC4WP: Mailchimp for WordPress
    2. Connect with API key
    3. Add signup forms to site

ConvertKit:

    1. Install ConvertKit plugin
    2. Configure forms and automation

API Integration Example

Access WordPress content programmatically:

JavaScript/Node.js:

const fetch = require('node-fetch');


// Get recent posts
async function getRecentPosts() {
  const response = await fetch('https://example-app.klutch.sh/wp-json/wp/v2/posts?per_page=5');
  const posts = await response.json();


  posts.forEach(post => {
    console.log(`Title: ${post.title.rendered}`);
    console.log(`Link: ${post.link}`);
    console.log(`Excerpt: ${post.excerpt.rendered}\n`);
  });
}


// Create a new post (requires authentication)
async function createPost(title, content, token) {
  const response = await fetch('https://example-app.klutch.sh/wp-json/wp/v2/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      title: title,
      content: content,
      status: 'publish'
    })
  });


  const post = await response.json();
  console.log(`Created post: ${post.link}`);
}


getRecentPosts();

Python:

import requests


# Get recent posts
response = requests.get('https://example-app.klutch.sh/wp-json/wp/v2/posts?per_page=5')
posts = response.json()


for post in posts:
    print(f"Title: {post['title']['rendered']}")
    print(f"Link: {post['link']}")
    print(f"Excerpt: {post['excerpt']['rendered']}\n")


# Create a new post (requires authentication)
def create_post(title, content, token):
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }


    data = {
        'title': title,
        'content': content,
        'status': 'publish'
    }


    response = requests.post(
        'https://example-app.klutch.sh/wp-json/wp/v2/posts',
        headers=headers,
        json=data
    )


    post = response.json()
    print(f"Created post: {post['link']}")

Migration Guide

Migrating from Existing WordPress Site

To migrate an existing WordPress site to Klutch.sh:

    1. Export Current Site:

      • Install All-in-One WP Migration
      • Export site (creates a .wpress file)
      • Or manually export database and wp-content folder

    2. Set Up New Klutch.sh Deployment:

      • Deploy WordPress following this guide
      • Complete initial WordPress installation

    3. Import Data:

      • Install All-in-One WP Migration on new site
      • Import the .wpress file
      • Or manually import database and upload wp-content files

    4. Update Configuration:

      • Update site URLs in database
      • Regenerate permalinks
      • Clear all caches

    5. Update DNS:

      • Point domain to new Klutch.sh deployment
      • Monitor for issues after DNS propagation

    6. Verify Migration:

      • Test all pages and functionality
      • Check forms, payment gateways, and integrations
      • Verify media files are accessible
      • Test user logins

Database URL Updates

After migration, update URLs in database:

-- Update site URL
UPDATE wp_options SET option_value = 'https://example-app.klutch.sh'
WHERE option_name IN ('siteurl', 'home');


-- Update post content URLs
UPDATE wp_posts SET post_content = REPLACE(post_content, 'oldsite.com', 'example-app.klutch.sh');


-- Update post metadata URLs
UPDATE wp_postmeta SET meta_value = REPLACE(meta_value, 'oldsite.com', 'example-app.klutch.sh');

Or use WP-CLI:

Terminal window
wp search-replace 'oldsite.com' 'example-app.klutch.sh' --all-tables

Resources and Further Reading

Conclusion

Deploying WordPress on Klutch.sh provides a robust, scalable solution for building and managing websites of any size. With automatic Docker detection, persistent storage for media and custom code, seamless database integration, and built-in SSL/TLS, you can focus on creating great content while Klutch.sh handles the infrastructure complexity.

This guide covered everything from basic deployment to advanced configuration, security best practices, performance optimization, troubleshooting, and integrations. Whether you’re launching a personal blog, building a business website, setting up an online store, or creating a custom web application, WordPress on Klutch.sh offers the flexibility, features, and reliability you need to succeed online.

With WordPress’s vast ecosystem of themes and plugins, combined with Klutch.sh’s simplified deployment and scaling capabilities, you have everything you need to build a professional web presence. The platform’s automatic updates, persistent storage, and easy database management mean you can spend less time on server maintenance and more time on what matters - creating and publishing great content.

For additional help or questions, refer to the resources above or reach out to the WordPress community and Klutch.sh support team.