Skip to content
Klutch.sh Docs

Deploying FlatPress

Introduction

FlatPress is a lightweight, flat-file blogging platform written in PHP that doesn’t require a database. It stores all content in plain text files, making it incredibly fast, portable, and easy to backup. With a simple admin interface, plugin support, and theme customization, FlatPress provides an elegant solution for bloggers who want simplicity without sacrificing functionality.

Deploying FlatPress on Klutch.sh gives you automatic Dockerfile detection, persistent storage for your content, HTTPS endpoints, and seamless scaling. This guide walks you through deploying FlatPress with a production-ready Dockerfile, configuring persistent volumes for content storage, and implementing best practices for a reliable blogging platform.

Why Deploy FlatPress on Klutch.sh?

  • Automatic Dockerfile Detection: Klutch.sh detects your Dockerfile automatically and builds your container
  • Persistent Storage: Attach volumes to preserve your blog content, themes, and plugins across deployments
  • Zero Database Management: FlatPress uses flat files, eliminating database complexity
  • Instant HTTPS: All deployments include automatic SSL/TLS certificates
  • Easy Scaling: Scale your blog’s resources based on traffic demands
  • Fast Backups: Simple file-based backups without database exports
  • GitHub Integration: Deploy directly from your GitHub repository
  • Environment Isolation: Run multiple FlatPress instances with isolated content

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your project
  • Docker installed locally for testing (optional but recommended)
  • Basic familiarity with Docker and PHP applications
  • Understanding of file permissions and web server configuration

Understanding FlatPress Architecture

FlatPress follows a simple PHP application architecture that relies on the file system rather than a database:

Core Components:

  • PHP Application Layer: Handles routing, content rendering, and admin interface
  • File-Based Storage: All posts, pages, and settings stored as plain text files
  • Plugin System: Extensible architecture for adding functionality
  • Theme Engine: Smarty-based templating system for customization
  • Admin Panel: Web-based interface for content management
  • Static File Cache: Optional caching for improved performance

Default Configuration:

  • Port: 80 (HTTP)
  • PHP Version: 7.4 to 8.2 (8.1 recommended)
  • Required Extensions: mbstring, xml, json, zlib, gd (for image manipulation)
  • Web Server: Apache with mod_rewrite (recommended)
  • Storage: File-based (no database required)

Directory Structure:

/var/www/html/
├── admin/              # Administration interface
├── fp-content/         # Blog content, themes, plugins
│   ├── cache/         # Template cache
│   ├── content/       # Posts and pages
│   ├── plugins/       # Installed plugins
│   └── themes/        # Installed themes
├── fp-includes/       # Core FlatPress files
├── res/               # Static resources (CSS, JS, images)
├── setup/             # Installation script (remove after setup)
└── index.php          # Main entry point

Installation and Setup

Step 1: Create Your Repository

    Create a new GitHub repository for your FlatPress deployment:

    Terminal window
    mkdir flatpress-deployment
    cd flatpress-deployment
    git init

Step 2: Create the Dockerfile

    Create a Dockerfile in the root of your repository. This Dockerfile will set up FlatPress with Apache and all necessary PHP extensions:

    FROM php:8.1-apache
    

    # Install system dependencies and PHP extensions
    RUN apt-get update && apt-get install -y \
        git \
        unzip \
        libpng-dev \
        libjpeg-dev \
        libfreetype6-dev \
        libxml2-dev \
        libzip-dev \
        zlib1g-dev \
        && rm -rf /var/lib/apt/lists/*
    

    # Install PHP extensions required by FlatPress
    RUN docker-php-ext-configure gd --with-freetype --with-jpeg && \
        docker-php-ext-install -j$(nproc) \
        gd \
        mbstring \
        xml \
        zip \
        opcache
    

    # Enable Apache modules
    RUN a2enmod rewrite headers expires
    

    # Set working directory
    WORKDIR /var/www/html
    

    # Download and install FlatPress
    RUN git clone https://github.com/flatpressblog/flatpress.git . && \
        chown -R www-data:www-data /var/www/html && \
        chmod -R 755 /var/www/html && \
        chmod -R 777 /var/www/html/fp-content
    

    # Create Apache configuration
    RUN echo '<VirtualHost *:80>\n\
        ServerAdmin webmaster@localhost\n\
        DocumentRoot /var/www/html\n\
        \n\
        <Directory /var/www/html>\n\
            Options -Indexes +FollowSymLinks\n\
            AllowOverride All\n\
            Require all granted\n\
        </Directory>\n\
        \n\
        # Security headers\n\
        Header always set X-Content-Type-Options "nosniff"\n\
        Header always set X-Frame-Options "SAMEORIGIN"\n\
        Header always set X-XSS-Protection "1; mode=block"\n\
        \n\
        ErrorLog ${APACHE_LOG_DIR}/error.log\n\
        CustomLog ${APACHE_LOG_DIR}/access.log combined\n\
    </VirtualHost>' > /etc/apache2/sites-available/000-default.conf
    

    # Expose port 80
    EXPOSE 80
    

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

    # Start Apache
    CMD ["apache2-foreground"]

    This Dockerfile:

    • Uses PHP 8.1 with Apache
    • Installs all required PHP extensions (GD, mbstring, XML, etc.)
    • Clones the latest FlatPress from GitHub
    • Configures Apache with security headers
    • Sets proper file permissions for content directories
    • Enables mod_rewrite for clean URLs

Step 3: Create an Apache .htaccess File (Optional)

    While FlatPress includes its own .htaccess file, you can create a custom one for additional security and performance:

    # Create a file named .htaccess
    # Block access to sensitive files
    <FilesMatch "^(config|defaults)\.php$">
        Require all denied
    </FilesMatch>
    

    # Enable compression
    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
    </IfModule>
    

    # Browser caching
    <IfModule mod_expires.c>
        ExpiresActive On
        ExpiresByType image/jpg "access plus 1 year"
        ExpiresByType image/jpeg "access plus 1 year"
        ExpiresByType image/gif "access plus 1 year"
        ExpiresByType image/png "access plus 1 year"
        ExpiresByType text/css "access plus 1 month"
        ExpiresByType application/javascript "access plus 1 month"
    </IfModule>
    

    # Clean URLs
    RewriteEngine On
    RewriteBase /
    

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.php [L]

    Note: Only add this if you need custom configurations beyond FlatPress’s default settings.

Step 4: Create a Custom Entrypoint Script (Optional)

    For advanced initialization, create a docker-entrypoint.sh file:

    #!/bin/bash
    

    set -e
    

    echo "Initializing FlatPress..."
    

    # Create necessary directories if they don't exist
    mkdir -p /var/www/html/fp-content/cache
    mkdir -p /var/www/html/fp-content/content
    mkdir -p /var/www/html/fp-content/attachs
    

    # Set proper permissions
    chown -R www-data:www-data /var/www/html
    chmod -R 755 /var/www/html
    chmod -R 777 /var/www/html/fp-content
    

    # Remove setup directory if it exists (security measure)
    if [ -d "/var/www/html/setup" ]; then
        echo "Warning: setup directory still exists. Consider removing it after installation."
    fi
    

    # Check if config file exists
    if [ ! -f "/var/www/html/fp-content/config.php" ]; then
        echo "FlatPress not yet configured. Please visit your site to complete setup."
    fi
    

    echo "Starting Apache..."
    exec apache2-foreground

    Make it executable and update your Dockerfile:

    Terminal window
    chmod +x docker-entrypoint.sh

    Update your Dockerfile’s final lines:

    # Copy entrypoint script
    COPY docker-entrypoint.sh /usr/local/bin/
    RUN chmod +x /usr/local/bin/docker-entrypoint.sh
    

    # Use custom entrypoint
    ENTRYPOINT ["docker-entrypoint.sh"]

Step 5: Create Environment Configuration File

    Create a .env.example file to document available environment variables:

    Terminal window
    # FlatPress Environment Configuration
    

    # Application Settings
    APP_NAME=FlatPress Blog
    APP_ENV=production
    APP_DEBUG=false
    

    # PHP Configuration
    PHP_MEMORY_LIMIT=256M
    PHP_MAX_EXECUTION_TIME=300
    PHP_UPLOAD_MAX_FILESIZE=50M
    PHP_POST_MAX_SIZE=50M
    

    # Apache Configuration
    APACHE_LOG_LEVEL=warn
    

    # Optional: Custom Domain
    # CUSTOM_DOMAIN=blog.example.com
    

    # Optional: Email Configuration (for plugins)
    # SMTP_HOST=smtp.example.com
    # SMTP_PORT=587
    # SMTP_USER=your-email@example.com
    # SMTP_PASS=your-password
    # SMTP_FROM=noreply@example.com

    Important: Never commit actual secrets to your repository. Set these as environment variables in Klutch.sh.

Step 6: Create a README

    Document your deployment setup in a README.md file:

    # FlatPress Deployment
    

    This repository contains the Docker configuration for deploying FlatPress on Klutch.sh.
    

    ## Features
    

    - PHP 8.1 with Apache
    - All required PHP extensions
    - Clean URLs with mod_rewrite
    - Security headers configured
    - Optimized for production use
    

    ## Deployment
    

    1. Push this repository to GitHub
    2. Create a new app on Klutch.sh
    3. Connect your GitHub repository
    4. Klutch.sh automatically detects and builds the Dockerfile
    5. Attach persistent volume at `/var/www/html/fp-content`
    6. Deploy and complete the web-based setup
    

    ## Local Development
    

    ```bash
    docker build -t flatpress .
    docker run -p 8080:80 -v $(pwd)/content:/var/www/html/fp-content flatpress

    Access at http://localhost:8080

    Backup

    Backup the /var/www/html/fp-content directory regularly to preserve:

    • Blog posts and pages
    • Themes and plugins
    • Configuration files
    • Uploaded attachments
    </ol>
    

    ### Step 7: Push to GitHub
    

    <ol>
    

    Add all files and push to your GitHub repository:
    

    ```bash
    # Create .gitignore
    cat > .gitignore << 'EOF'
    .env
    .DS_Store
    *.log
    fp-content/cache/*
    fp-content/content/*
    !fp-content/content/.gitkeep
    EOF
    

    # Initialize git and commit
    git add Dockerfile .env.example README.md .gitignore
    git commit -m "Initial FlatPress deployment setup"
    git branch -M main
    git remote add origin https://github.com/YOUR_USERNAME/flatpress-deployment.git
    git push -u origin main

Deploying to Klutch.sh

Now that your repository is ready, follow these steps to deploy FlatPress on Klutch.sh:

  1. Log in to Klutch.sh

    Navigate to klutch.sh/app and sign in with your account.

  2. Create a New Project

    Click “Create Project” and give your project a descriptive name like “FlatPress Blog”.

  3. Create a New App

    Inside your project, click “Create App” to start a new deployment.

  4. Connect Your GitHub Repository

    • Select GitHub as your source
    • Authorize Klutch.sh to access your repositories if you haven’t already
    • Choose the repository containing your FlatPress Dockerfile
    • Select the branch you want to deploy (typically main)

  5. Configure Traffic Settings

    • Select HTTP as the traffic type (FlatPress is a web application)
    • Klutch.sh will automatically route traffic to your application

  6. Set Internal Port

    Set the internal port to 80 (the port Apache listens on inside the container).

  7. Add Environment Variables (Optional)

    While FlatPress doesn’t require environment variables for basic operation, you can add these for customization:

    • PHP_MEMORY_LIMIT: 256M (adjust based on your needs)
    • PHP_UPLOAD_MAX_FILESIZE: 50M (for larger uploads)
    • PHP_POST_MAX_SIZE: 50M (should match upload size)

  8. Attach Persistent Volume

    This is crucial for preserving your blog content:

    • Click “Add Volume”
    • Mount Path: /var/www/html/fp-content
    • Size: Start with 5GB (adjust based on expected content)

    This ensures your posts, themes, plugins, and uploads persist across deployments.

  9. Review and Deploy

    • Review all configuration settings
    • Click “Deploy” to start the build process

    Klutch.sh will:

    • Clone your repository
    • Build the Docker image
    • Install all dependencies
    • Start the container
    • Provision an HTTPS endpoint

    The build typically takes 3-5 minutes.

  10. Access Your FlatPress Installation

    Once deployment completes, you’ll receive a URL like https://example-app.klutch.sh. Visit this URL to complete the FlatPress setup wizard.

Post-Deployment Configuration

Complete the FlatPress Setup Wizard

  1. Visit your deployment URL (e.g., https://example-app.klutch.sh)

  2. You’ll be greeted by the FlatPress setup wizard. Follow these steps:

    1. Language Selection: Choose your preferred language
    2. Site Configuration:
      • Set your blog title
      • Enter your name and email
      • Choose your timezone
    3. Admin Account: Create your administrator username and password
    4. Permalinks: Choose your URL structure (clean URLs recommended)
    5. Complete Installation: Click finish to finalize setup

  3. Remove the Setup Directory (Important for Security)

    After completing setup, the setup directory should be removed. You have two options:

    Option A: Update your Dockerfile to remove it automatically:

    # Add after the git clone command
    RUN git clone https://github.com/flatpressblog/flatpress.git . && \
        rm -rf /var/www/html/setup && \
        chown -R www-data:www-data /var/www/html

    Then redeploy your app.

    Option B: Create a new deployment that removes setup on startup by using the entrypoint script from Step 4 and adding:

    Terminal window
    # In docker-entrypoint.sh
    rm -rf /var/www/html/setup

Access Your Admin Panel

    Access the admin interface at https://example-app.klutch.sh/admin using your administrator credentials.

    From here you can:

    • Write and publish blog posts
    • Manage pages
    • Install themes and plugins
    • Configure site settings
    • Moderate comments
    • View statistics

Configure Custom Domain (Optional)

    To use a custom domain:

    1. Go to your Klutch.sh dashboard
    2. Navigate to your app’s settings
    3. Add your custom domain (e.g., blog.example.com)
    4. Update your DNS records to point to Klutch.sh
    5. Wait for DNS propagation (usually 5-60 minutes)

    Klutch.sh automatically provisions SSL certificates for custom domains.

Production Best Practices

Security Hardening

  1. Remove Setup Directory: Always remove the setup directory after installation to prevent unauthorized reinstallation

  2. Use Strong Passwords: Create complex admin passwords with a mix of characters, numbers, and symbols

  3. Keep FlatPress Updated: Regularly update to the latest version by rebuilding with the latest code:

    Terminal window
    # In your Dockerfile, you can pin to a specific version:
    RUN git clone --branch 1.3 https://github.com/flatpressblog/flatpress.git .

  4. Limit Login Attempts: Consider installing a plugin that limits failed login attempts

  5. Regular Backups: Schedule regular backups of the persistent volume containing fp-content

  6. File Permissions: Ensure proper permissions are set (755 for directories, 644 for files, except writable areas)

Performance Optimization

  1. Enable Caching: FlatPress includes built-in caching. Enable it in the admin panel under Settings → Advanced

  2. Optimize Images: Compress images before uploading to reduce storage and improve load times

  3. Use a CDN: For static assets, consider using a CDN service to reduce server load

  4. PHP OpCache: Already enabled in the Dockerfile, but ensure it’s configured:

    # Add to Dockerfile
    RUN echo "opcache.memory_consumption=128" >> /usr/local/etc/php/conf.d/opcache.ini && \
        echo "opcache.interned_strings_buffer=8" >> /usr/local/etc/php/conf.d/opcache.ini && \
        echo "opcache.max_accelerated_files=4000" >> /usr/local/etc/php/conf.d/opcache.ini && \
        echo "opcache.revalidate_freq=60" >> /usr/local/etc/php/conf.d/opcache.ini

  5. Apache Configuration: The Dockerfile includes optimized Apache settings. Monitor your access logs to identify performance bottlenecks.

Backup Strategy

  1. Automated Backups: Set up automated backups of your persistent volume through your Klutch.sh dashboard

  2. Export Content Regularly: Download your fp-content directory periodically:

    Terminal window
    # Using Klutch.sh CLI or backup tools
    # The fp-content directory contains all your critical data

  3. Version Control for Themes: If you customize themes, keep them in a separate git repository

  4. Database-less Advantage: Since FlatPress is flat-file, backups are simpler - just copy the files!

Monitoring and Maintenance

  1. Monitor Resource Usage: Check your Klutch.sh dashboard for CPU and memory usage patterns

  2. Apache Logs: Access logs through your Klutch.sh dashboard to identify errors or unusual activity

  3. Disk Space: Monitor your persistent volume usage and increase size if needed

  4. Update Schedule: Plan monthly checks for FlatPress updates and plugin updates

  5. Comment Moderation: Regularly moderate comments to prevent spam

Troubleshooting

Common Issues and Solutions

  1. Problem: Setup wizard not appearing

    Solution:

    • Ensure the setup directory exists in the container
    • Check that Apache is serving files from /var/www/html
    • Verify file permissions are correct (755 for directories)

  2. Problem: “Permission denied” errors when saving content

    Solution:

    Terminal window
    # Ensure fp-content directory is writable
    chmod -R 777 /var/www/html/fp-content

    Or in your Dockerfile:

    RUN chmod -R 777 /var/www/html/fp-content

  3. Problem: Clean URLs not working (404 errors)

    Solution:

    • Verify mod_rewrite is enabled in Apache
    • Check that .htaccess file exists in the root directory
    • Ensure AllowOverride All is set in Apache configuration

  4. Problem: Images not uploading

    Solution:

    • Check PHP upload limits in environment variables
    • Verify /var/www/html/fp-content/attachs is writable
    • Increase PHP_UPLOAD_MAX_FILESIZE and PHP_POST_MAX_SIZE

  5. Problem: Slow performance

    Solution:

    • Enable FlatPress caching in admin settings
    • Enable PHP OpCache (included in Dockerfile)
    • Scale up your Klutch.sh instance size
    • Optimize images before uploading
    • Check for resource-intensive plugins

  6. Problem: Lost content after redeployment

    Solution:

    • Verify persistent volume is attached to /var/www/html/fp-content
    • Check volume mount path is correct in Klutch.sh settings
    • Ensure the volume wasn’t deleted

Health Check Failures

    If health checks fail:

    1. Check Apache logs in Klutch.sh dashboard
    2. Verify port 80 is exposed and Apache is running
    3. Test the health check endpoint manually:
    Terminal window
    curl -f http://localhost/
    1. Increase health check timeout in Dockerfile if needed:
    HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3

Debug Mode

    To enable debug mode for troubleshooting:

    1. Edit /var/www/html/fp-content/config.php in your persistent volume
    2. Set debug mode to true:
    $fp_config['general']['debug_mode'] = 1;

    Note: Disable debug mode in production after troubleshooting.

Advanced Configuration

Custom PHP Settings

    Add custom PHP configuration by creating a php.ini file:

    ; Custom PHP settings for FlatPress
    memory_limit = 256M
    upload_max_filesize = 50M
    post_max_size = 50M
    max_execution_time = 300
    max_input_time = 300
    

    ; Security
    display_errors = Off
    log_errors = On
    error_log = /var/log/php_errors.log
    

    ; Performance
    opcache.enable = 1
    opcache.memory_consumption = 128
    opcache.interned_strings_buffer = 8
    opcache.max_accelerated_files = 4000

    Update your Dockerfile to copy this file:

    COPY php.ini /usr/local/etc/php/conf.d/custom.ini

Install Plugins and Themes

  1. Through Admin Panel: The easiest method is using the built-in plugin/theme installer in the FlatPress admin panel

  2. Manual Installation:

    Upload plugins to /var/www/html/fp-content/plugins/ and themes to /var/www/html/fp-content/themes/

  3. Include in Dockerfile (for core plugins):

    RUN cd /var/www/html/fp-content/plugins && \
        git clone https://github.com/plugin-author/plugin-name.git

Multi-User Setup

    FlatPress supports multiple authors:

    1. Go to Admin Panel → Users
    2. Create additional user accounts
    3. Assign appropriate roles and permissions
    4. Each user can create and manage their own posts

Email Configuration

    To enable email notifications (requires a plugin):

    1. Install an SMTP plugin from the FlatPress plugin directory
    2. Configure SMTP settings in the admin panel:
      • SMTP Host
      • SMTP Port (usually 587)
      • Authentication credentials
      • From address

Scaling and Performance

Vertical Scaling

    Increase resources for your FlatPress instance:

    1. Navigate to your app in the Klutch.sh dashboard
    2. Adjust compute resources (CPU/Memory)
    3. Recommended starting point: 1 CPU, 512MB RAM
    4. Scale up for high-traffic blogs: 2 CPU, 1GB RAM

Horizontal Scaling

    While FlatPress is file-based, horizontal scaling requires additional considerations:

    1. Use a shared persistent volume across instances (if supported)
    2. Implement a caching layer (e.g., Varnish, Nginx caching)
    3. Consider using a CDN for static assets
    4. For true horizontal scaling, consider database-backed alternatives

Content Delivery Optimization

  1. Image Optimization: Use plugins that automatically optimize images on upload

  2. Static Caching: Enable FlatPress’s built-in caching system

  3. Browser Caching: Already configured in the Dockerfile’s Apache settings

  4. Minification: Use plugins to minify CSS and JavaScript

Migrating from Another Blog Platform

From WordPress

  1. Export your WordPress content as XML

  2. Use a conversion tool or manually convert posts to FlatPress format

  3. Upload converted files to /var/www/html/fp-content/content/

  4. Set proper file permissions

From Other Flat-File Systems

  1. Export content from your current platform

  2. Convert to FlatPress’s file structure (plain text with YAML frontmatter)

  3. Upload to the content directory

  4. Rebuild cache through the admin panel

Additional Resources

  1. Official Documentation: FlatPress Documentation

  2. GitHub Repository: FlatPress on GitHub

  3. Plugin Directory: FlatPress Plugins

  4. Theme Directory: FlatPress Themes

  5. Community Forum: FlatPress Forum

  6. Docker Documentation: Docker Docs

  7. PHP Documentation: PHP Manual

  8. Apache Documentation: Apache HTTP Server Docs

  9. Klutch.sh Support: For platform-specific questions, visit the Klutch.sh documentation

Production Checklist

Before going live with your FlatPress blog, verify:

    • Dockerfile builds successfully
    • Persistent volume attached to /var/www/html/fp-content
    • Setup directory removed after installation
    • Strong admin password configured
    • Clean URLs working correctly
    • Image uploads functioning properly
    • Caching enabled in FlatPress settings
    • PHP OpCache configured and enabled
    • Apache security headers present
    • Custom domain configured (if using)
    • SSL certificate provisioned
    • File permissions set correctly (755/644)
    • Backup strategy implemented
    • Monitoring configured in Klutch.sh dashboard
    • Comment moderation settings configured
    • Email notifications working (if applicable)
    • Theme customized and responsive
    • Essential plugins installed and activated
    • Performance tested under expected load
    • Error logs reviewed for issues
    • Health checks passing consistently

Conclusion

Deploying FlatPress on Klutch.sh gives you a lightweight, fast, and maintainable blogging platform without the complexity of database management. The flat-file architecture makes backups simple, deployments fast, and maintenance minimal.

With this guide, you now have:

  • A production-ready Dockerfile for FlatPress
  • Persistent storage configuration for content preservation
  • Security best practices for production deployments
  • Performance optimization strategies
  • Troubleshooting solutions for common issues
  • A comprehensive understanding of FlatPress architecture

Start blogging with the simplicity of flat files and the power of Klutch.sh’s infrastructure. Your content is portable, your setup is simple, and your blog is ready to scale.

For questions or issues specific to Klutch.sh deployments, refer to the platform documentation or contact support. Happy blogging!