Skip to content
Klutch.sh Docs

Deploying Typemill

Introduction

Typemill is a lightweight, flat-file CMS designed specifically for creating professional documentation and content-focused websites. Built with PHP and using Markdown files for content storage, Typemill eliminates database complexity while providing a polished editing experience with both visual and raw markdown editors.

Unlike database-driven CMS platforms, Typemill stores all content in markdown files, making it easy to backup, version control, and migrate. Its focus on documentation and structured content makes it ideal for technical documentation, user manuals, knowledge bases, and content-heavy websites.

Key highlights of Typemill:

  • Flat-File Architecture: No database required, content stored in markdown files
  • Visual Editor: WYSIWYG block editor for non-technical users
  • Markdown Support: Full markdown support with syntax highlighting
  • Navigation Builder: Drag-and-drop navigation structure
  • Theme System: Professional themes with customization options
  • Plugin Architecture: Extend functionality with plugins
  • Multi-User: Multiple authors with role-based permissions
  • Media Manager: Upload and manage images and files
  • SEO Friendly: Built-in meta tag management and clean URLs
  • Version History: Track content changes over time
  • Open Source: Licensed under MIT

This guide walks through deploying Typemill on Klutch.sh using Docker, setting up your documentation site, and configuring the CMS for content creation.

Why Deploy Typemill on Klutch.sh

Deploying Typemill on Klutch.sh provides several advantages for documentation sites:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Typemill without complex configuration. Push to GitHub, and your documentation site deploys automatically.

Persistent Storage: Attach persistent volumes for your content files and media uploads. Your documentation survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your documentation.

GitHub Integration: Connect your content repository directly from GitHub. Updates trigger automatic redeployments.

Low Resource Usage: Typemill’s flat-file architecture means minimal server resources for excellent performance.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your Typemill configuration
  • Basic familiarity with Docker and CMS concepts
  • Content ready to publish (or plans to create it)
  • (Optional) A custom domain for your Typemill site

Understanding Typemill Architecture

Typemill is built on a simple, efficient architecture:

PHP Application: The core CMS built with PHP and the Slim framework.

Markdown Content: All content is stored as markdown files in a structured directory.

YAML Configuration: Settings and metadata stored in YAML files.

File-Based Media: Images and files stored directly on the filesystem.

Theme System: Twig-based templating for complete design control.

Preparing Your Repository

To deploy Typemill on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

typemill-deploy/
├── Dockerfile
├── content/
│   └── .gitkeep
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.2-apache


# Install required extensions
RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip \
    && a2enmod rewrite


# Download and extract Typemill
WORKDIR /var/www/html
RUN curl -L https://github.com/typemill/typemill/archive/refs/heads/master.zip -o typemill.zip \
    && unzip typemill.zip \
    && mv typemill-master/* . \
    && rm -rf typemill-master typemill.zip


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


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


# Expose port
EXPOSE 80


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

Environment Variables Reference

VariableRequiredDefaultDescription
TYPEMILL_SETTINGS_HEADLINEANCHORSNotrueEnable headline anchors
TYPEMILL_SETTINGS_MARKDOWNNotrueEnable markdown editor

Deploying Typemill on Klutch.sh

Once your repository is prepared, follow these steps to deploy Typemill:

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile .dockerignore
    git commit -m "Initial Typemill deployment configuration"
    git remote add origin https://github.com/yourusername/typemill-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “typemill” or “docs”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Typemill Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80 (Apache default port)

    Attach Persistent Volumes

    Persistent storage is essential for Typemill. Add the following volumes:

    Mount PathRecommended SizePurpose
    /var/www/html/content1 GBMarkdown content files
    /var/www/html/media5 GBUploaded images and files
    /var/www/html/settings100 MBCMS configuration
    /var/www/html/cache500 MBGenerated cache files

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Typemill container
    • Provision an HTTPS certificate

    Access Typemill

    Once deployment completes, access your Typemill instance at https://your-app-name.klutch.sh. The first-time setup wizard will guide you through configuration.

Initial Setup and Configuration

First-Time Setup

When you first access Typemill:

  1. The setup wizard checks system requirements
  2. Create your admin account
  3. Configure basic site settings
  4. Choose a theme
  5. Complete setup

Site Settings

Configure your site in the admin panel:

  1. Log in to /tm/login
  2. Go to Settings
  3. Configure:
    • Site title and description
    • Author information
    • Theme selection
    • Navigation settings

Theme Configuration

Customize your theme:

  1. Navigate to Themes section
  2. Activate your preferred theme
  3. Configure theme options:
    • Colors and branding
    • Navigation style
    • Footer content
    • Custom CSS

Content Creation

Creating Pages

Add new content pages:

  1. Go to the Content section
  2. Click ”+” to add a new page
  3. Enter the page title
  4. Use the visual editor or markdown editor
  5. Save and publish

Content Structure

Organize content hierarchically:

content/
├── 01-getting-started/
│   ├── index.md
│   ├── 01-installation.md
│   └── 02-configuration.md
├── 02-user-guide/
│   ├── index.md
│   └── 01-basics.md
└── 03-reference/
    └── index.md

Visual Editor

The block editor supports:

  • Headings and paragraphs
  • Lists (ordered and unordered)
  • Code blocks with syntax highlighting
  • Images and media
  • Tables
  • Quotes and callouts
  • Custom blocks via plugins

Markdown Editor

Switch to raw markdown for:

  • Complex formatting
  • Code-heavy content
  • Batch imports
  • Git-based workflows

Drag-and-Drop Navigation

Organize your site structure:

  1. Go to the Navigation section
  2. Drag pages to reorder
  3. Create nested hierarchies
  4. Hide pages from navigation
  5. Save changes

Custom Navigation

Add external links or custom items to navigation through the admin panel.

Media Management

Uploading Images

Add images to your content:

  1. Click the image button in the editor
  2. Upload or select existing images
  3. Set alt text and captions
  4. Resize if needed

File Management

Manage all media files:

  1. Go to Media section
  2. View all uploaded files
  3. Organize into folders
  4. Delete unused files

User Management

Creating Users

Add authors and editors:

  1. Navigate to Users section
  2. Click “Add User”
  3. Set username, email, password
  4. Assign role

User Roles

Available roles include:

  • Admin: Full access to all settings and content
  • Editor: Can edit and publish content
  • Author: Can create and edit own content
  • Guest: View-only access

Plugins

Installing Plugins

Extend Typemill with plugins:

  1. Download plugins from the Typemill site
  2. Upload to /plugins directory
  3. Activate in the Plugins section
  4. Configure plugin settings

Useful plugins include:

  • Math: LaTeX equation support
  • Highlight: Syntax highlighting
  • Search: Full-text search
  • Comments: Discussion on pages

Production Best Practices

Content Backup

Protect your content:

  1. Back up the /content directory regularly
  2. Version control your markdown files with Git
  3. Export media files periodically
  4. Document your configuration

Performance Optimization

  • Enable caching in settings
  • Optimize images before upload
  • Use a CDN for static assets
  • Minimize plugins

Security

  • Use strong admin passwords
  • Keep Typemill updated
  • HTTPS is provided by Klutch.sh
  • Limit user accounts

Troubleshooting Common Issues

Permission Errors

Symptoms: Cannot save content or upload files.

Solutions:

  • Check volume permissions
  • Verify www-data ownership
  • Review directory permissions

Content Not Displaying

Symptoms: Pages show errors or blank.

Solutions:

  • Verify markdown syntax
  • Check file encoding (UTF-8)
  • Clear the cache
  • Review error logs

Theme Issues

Symptoms: Theme not applying correctly.

Solutions:

  • Check theme compatibility
  • Clear browser cache
  • Verify theme files are complete

Additional Resources

Conclusion

Deploying Typemill on Klutch.sh gives you a lightweight, powerful documentation CMS accessible from anywhere. The combination of Typemill’s flat-file simplicity and Klutch.sh’s deployment automation means you can focus on creating great content rather than managing infrastructure.

With visual editing, markdown support, and a flexible theme system, Typemill provides everything you need for professional documentation sites. Your content remains portable, version-controllable, and backed by reliable infrastructure.