Deploying HTMLy

Introduction

HTMLy is a fast, simple, and powerful databaseless blogging platform built with PHP. Instead of relying on a database like MySQL or PostgreSQL, HTMLy stores all content as flat files in Markdown format. This approach eliminates database complexity while maintaining a full-featured blogging experience.

The platform emphasizes simplicity without sacrificing functionality. HTMLy includes everything you need for blogging: posts, pages, categories, tags, comments, and an intuitive admin interface. Being databaseless means easier backups, simpler migrations, and reduced server requirements.

Key highlights of HTMLy:

• Databaseless: All content stored as Markdown files
• Fast Performance: No database queries means quick page loads
• Markdown Editor: Write posts in Markdown with live preview
• Multi-User Support: Multiple authors with different roles
• SEO Friendly: Clean URLs and proper meta tags out of the box
• Responsive Design: Works on all devices
• Theme System: Customizable themes and templates
• Static Page Support: Create pages outside of the blog
• Comment System: Built-in commenting without external services
• Search Functionality: Full-text search across content
• RSS Feeds: Automatic feed generation
• Open Source: Licensed under GPL-3.0

This guide walks through deploying HTMLy on Klutch.sh using Docker, configuring your blog, and publishing content.

Why Deploy HTMLy on Klutch.sh

Deploying HTMLy on Klutch.sh provides several advantages for running your blog:

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

Persistent Storage: Attach persistent volumes for your content files. Your posts and uploads survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your blog and admin panel.

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

Scalable Resources: Allocate CPU and memory based on expected traffic.

Environment Variable Management: Configure site settings through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for your professional blog presence.

Always-On Availability: Your blog remains accessible 24/7 for readers worldwide.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and PHP
• (Optional) A custom domain for your blog

Understanding HTMLy Architecture

HTMLy’s architecture is elegantly simple:

PHP Application: The core application handles routing, rendering, and administration.

Flat File Storage: All content stored in the file system:

• Posts in /content/[username]/blog/
• Pages in /content/[username]/static/
• Configuration in /config/

Content Format: Posts and pages written in Markdown with YAML front matter for metadata.

Theme System: Templates rendered with PHP, customizable through the /themes/ directory.

Directory Structure

htmly/
├── config/
│   ├── config.ini
│   └── users/
├── content/
│   └── [username]/
│       ├── blog/
│       └── static/
├── themes/
│   └── starter/
└── cache/

Preparing Your Repository

To deploy HTMLy on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

htmly-deploy/
├── Dockerfile
├── config/
│   └── config.ini
├── nginx.conf
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for HTMLy:

FROM php:8.2-fpm-alpine

# Install dependencies
RUN apk add --no-cache \
    nginx \
    git \
    supervisor \
    && docker-php-ext-install opcache

# Create directories
RUN mkdir -p /var/www/html /run/nginx /var/log/supervisor

# Clone HTMLy
WORKDIR /var/www/html
RUN git clone --depth 1 https://github.com/danpros/htmly.git .

# Set permissions
RUN chown -R www-data:www-data /var/www/html
RUN chmod -R 755 /var/www/html
RUN chmod -R 777 /var/www/html/cache /var/www/html/content /var/www/html/config

# Copy configuration files
COPY config/config.ini /var/www/html/config/config.ini
COPY nginx.conf /etc/nginx/http.d/default.conf

# Create supervisor configuration
RUN echo -e '[supervisord]\nnodaemon=true\n\n[program:php-fpm]\ncommand=php-fpm -F\n\n[program:nginx]\ncommand=nginx -g "daemon off;"' > /etc/supervisor/conf.d/supervisord.conf

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

# Start services
CMD ["supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

Nginx Configuration

Create an nginx.conf file:

server {
    listen 8080;
    server_name _;
    root /var/www/html;
    index index.php;

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # Handle requests
    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # PHP processing
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Deny access to sensitive files
    location ~ /\. {
        deny all;
    }

    location ~ ^/(config|content)/ {
        deny all;
    }

    # Cache static files
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}

HTMLy Configuration

Create config/config.ini:

; HTMLy Configuration

[site]
site.title = "My Blog"
site.tagline = "Thoughts and ideas"
site.description = "A personal blog powered by HTMLy"
site.url = "${SITE_URL}"

[admin]
admin.email = "${ADMIN_EMAIL}"

[settings]
timezone = "UTC"
posts.per.page = 10
comment.system = htmly

[appearance]
blog.theme = starter
blog.layout = timeline.list

[features]
enable.markdown = true
enable.cache = true
enable.tags = true
enable.search = true

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
SITE_URL	Yes	-	Full URL of your blog (e.g., https://blog.example.com)
ADMIN_EMAIL	Yes	-	Administrator email address

Deploying HTMLy on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add .
git commit -m "Initial HTMLy blog configuration"
git remote add origin https://github.com/yourusername/htmly-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. Name it something descriptive like “blog” or “htmly”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your HTMLy repository.

Configure HTTP Traffic

HTMLy serves its interface over HTTP:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Configure the following environment variables:

Variable	Value
SITE_URL	https://your-app.klutch.sh (or your custom domain)
ADMIN_EMAIL	Your email address

Attach Persistent Volumes

Add persistent storage for content:

Mount Path	Recommended Size	Purpose
/var/www/html/content	5 GB	Blog posts, pages, and uploads
/var/www/html/config	100 MB	Configuration and user data
/var/www/html/cache	500 MB	Cached pages for performance

Deploy Your Application

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

• Build the container image
• Install HTMLy and dependencies
• Start the web server
• Provision an HTTPS certificate

Complete Initial Setup

Access your blog and complete the installation wizard to create your admin account.

Initial Setup and Configuration

Installation Wizard

When you first access HTMLy, the installation wizard guides you through setup:

1. Enter your site title and tagline
2. Create your admin username and password
3. Configure your email address
4. Complete the installation

Creating Your First Post

1. Log in to the admin panel at /admin
2. Click “Add Content” then “Add Blog Post”
3. Enter your title and content in Markdown
4. Add categories and tags
5. Publish or save as draft

Writing in Markdown

HTMLy uses Markdown for content. Example:

## Introduction

This is a **bold** statement and this is *italicized*.

### Code Example

```php
echo "Hello, World!";

• List item one
• List item two
• List item three

### Creating Static Pages

For non-blog content like About or Contact pages:

1. Click "Add Content" then "Add Static Page"
2. Enter page title and content
3. Set the page URL slug
4. Publish the page

## Customization

### Theme Selection

HTMLy includes several themes. To change themes:

1. Go to Admin > Config > Theming
2. Select your preferred theme
3. Save changes

### Custom Themes

Create custom themes in `/themes/[theme-name]/`:

themes/ └── custom/ ├── main.html.php ├── post.html.php ├── static.html.php └── css/ └── style.css

### Site Configuration

Modify settings through the admin interface or by editing `config.ini`:

| Setting | Description |
|---------|-------------|
| `site.title` | Blog title in header |
| `site.tagline` | Subtitle/tagline |
| `posts.per.page` | Number of posts per page |
| `blog.theme` | Active theme name |

## User Management

### Adding Authors

Add multiple authors to your blog:

1. Go to Admin > Users
2. Click "Add User"
3. Set username, email, and password
4. Assign role (admin or user)

### User Roles

| Role | Capabilities |
|------|--------------|
| **Admin** | Full access to all settings and content |
| **User** | Can create and edit own posts |

## Production Best Practices

### Security Recommendations

- **Strong Passwords**: Use complex passwords for all accounts
- **Regular Updates**: Keep HTMLy updated to the latest version
- **Backup Configuration**: Regularly back up config directory
- **HTTPS Only**: Always use HTTPS in production

### Performance Optimization

- **Enable Caching**: Keep caching enabled for faster page loads
- **Optimize Images**: Compress images before uploading
- **CDN Integration**: Consider a CDN for static assets
- **OPcache**: Ensure PHP OPcache is enabled

### Backup Strategy

Back up these directories regularly:

- `/content/` - All your posts and pages
- `/config/` - Configuration and user data

Since HTMLy is databaseless, backing up is as simple as copying these directories.

## Troubleshooting Common Issues

### Page Not Found Errors

**Symptoms**: Posts or pages return 404 errors.

**Solutions**:

- Verify nginx rewrite rules are working
- Check file permissions on content directory
- Ensure cache is cleared after changes
- Review URL configuration in config.ini

### Permission Issues

**Symptoms**: Cannot save posts or configuration.

**Solutions**:

- Check that content and config directories are writable
- Verify www-data owns the files
- Set appropriate chmod permissions (755 for directories, 644 for files)

### Admin Panel Inaccessible

**Symptoms**: Cannot access /admin.

**Solutions**:

- Verify user account exists in config/users
- Clear browser cache and cookies
- Check for PHP errors in logs
- Verify session storage is working

### Slow Performance

**Symptoms**: Pages load slowly.

**Solutions**:

- Enable caching if disabled
- Clear and regenerate cache
- Check OPcache is enabled
- Optimize large images

## Additional Resources

- <a href="https://www.htmly.com/" target="_blank" rel="noopener noreferrer">HTMLy Official Website</a>
- <a href="https://github.com/danpros/htmly" target="_blank" rel="noopener noreferrer">HTMLy GitHub Repository</a>
- <a href="https://www.htmly.com/docs" target="_blank" rel="noopener noreferrer">HTMLy Documentation</a>
- <a href="https://www.htmly.com/blog/category/tutorial" target="_blank" rel="noopener noreferrer">HTMLy Tutorials</a>
- <a href="https://www.markdownguide.org/" target="_blank" rel="noopener noreferrer">Markdown Guide</a>
- <a href="/concepts/volumes" target="_blank" rel="noopener noreferrer">Klutch.sh Persistent Volumes</a>
- <a href="/concepts/deployments" target="_blank" rel="noopener noreferrer">Klutch.sh Deployments</a>

## Conclusion

Deploying HTMLy on Klutch.sh gives you a fast, simple blogging platform without database complexity. The combination of HTMLy's flat-file architecture and Klutch.sh's deployment simplicity means you can focus on writing content rather than managing infrastructure.

With Markdown support, multiple themes, and easy backups, HTMLy on Klutch.sh provides everything you need for a professional blog that's simple to maintain and fast to load.