Deploying Mataroa

Introduction

Mataroa is a minimalist, self-hosted blogging platform that focuses on what matters most: writing. With no JavaScript, no trackers, and no unnecessary features, Mataroa provides a clean, distraction-free environment for publishing your thoughts to the web.

Built with Python and Django, Mataroa embraces the philosophy that simplicity is the ultimate sophistication. It offers just enough features to run a professional blog while avoiding the bloat that plagues many modern content management systems.

Key highlights of Mataroa:

Minimalist Design: Clean, fast-loading pages with no JavaScript required
Markdown Support: Write posts in Markdown with live preview
No Tracking: Zero analytics, trackers, or third-party scripts by default
RSS Feeds: Built-in RSS feed generation for subscribers
Custom Domains: Use your own domain for a professional presence
Email Newsletters: Optional email notifications for new posts
Export Functionality: Export all your posts at any time
SEO Friendly: Clean URLs and proper meta tags
Lightweight: Minimal resource requirements
Open Source: BSD licensed with transparent development

This guide walks through deploying Mataroa on Klutch.sh using Docker, setting up your blog, and customizing your writing environment.

Why Deploy Mataroa on Klutch.sh

Deploying Mataroa on Klutch.sh provides several advantages:

Complete Control: Own your content and platform without depending on hosted services.

Always Available: Your blog runs 24/7 without managing servers.

HTTPS by Default: Automatic SSL certificates for professional, secure blogging.

Persistent Storage: Your posts persist across deployments.

Custom Domains: Use your own domain for brand identity.

Minimal Resources: Mataroa’s lightweight nature means efficient resource usage.

Prerequisites

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

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

Understanding Mataroa Architecture

Mataroa follows a simple, traditional web application architecture:

Django Application: The core blog engine built on Python’s Django framework.

PostgreSQL Database: Stores posts, user information, and blog settings.

Static Files: Minimal CSS for clean, fast-loading pages.

No External Dependencies: No CDNs, no JavaScript libraries, no tracking.

Preparing Your Repository

To deploy Mataroa on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

mataroa-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM mataroa/mataroa:latest

# Environment configuration
ENV DJANGO_SETTINGS_MODULE=mataroa.settings
ENV PORT=8000

# Database configuration
ENV DATABASE_URL=${DATABASE_URL}

# Secret key for Django
ENV SECRET_KEY=${SECRET_KEY}

# Allowed hosts
ENV ALLOWED_HOSTS=${ALLOWED_HOSTS}

# Email configuration (optional)
ENV EMAIL_HOST=${EMAIL_HOST:-}
ENV EMAIL_PORT=${EMAIL_PORT:-587}
ENV EMAIL_HOST_USER=${EMAIL_HOST_USER:-}
ENV EMAIL_HOST_PASSWORD=${EMAIL_HOST_PASSWORD:-}

# Expose the web interface port
EXPOSE 8000

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
__pycache__/
*.pyc

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`SECRET_KEY`	Yes	-	Django secret key (50+ random characters)
`ALLOWED_HOSTS`	Yes	-	Comma-separated list of allowed hostnames
`EMAIL_HOST`	No	-	SMTP server for email notifications
`EMAIL_PORT`	No	`587`	SMTP port
`EMAIL_HOST_USER`	No	-	SMTP username
`EMAIL_HOST_PASSWORD`	No	-	SMTP password

Deploying Mataroa on Klutch.sh

Mataroa requires PostgreSQL for data storage.

Generate a Secret Key

Generate a secure secret key for Django:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Or use:

openssl rand -base64 50

Save this key securely for the environment variables configuration.

Set Up PostgreSQL

Either use Klutch.sh’s managed PostgreSQL or deploy your own instance. You’ll need a connection string like:

postgresql://user:password@host:5432/mataroa

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Mataroa deployment configuration"
git remote add origin https://github.com/yourusername/mataroa-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 “mataroa” or “blog”.

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 Mataroa Dockerfile.

Configure HTTP Traffic

Mataroa serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`DATABASE_URL`	Your PostgreSQL connection string
`SECRET_KEY`	Your generated secret key
`ALLOWED_HOSTS`	`your-app-name.klutch.sh` (or your custom domain)

Deploy Your Application

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

Detect your Dockerfile automatically
Build the container image
Start the Mataroa container
Provision an HTTPS certificate

Run Database Migrations

After deployment, you may need to run database migrations. Access your container and run:

python manage.py migrate

Access Mataroa

Once deployment completes, access your instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Creating Your Account

When you first access Mataroa:

Navigate to /accounts/create/ to create your account
Enter your username, email, and password
This creates your blog at username.yourdomain.com (in single-blog mode)

Blog Configuration

After logging in, configure your blog:

Go to Settings or Blog Settings
Set your blog title
Add a blog description
Configure your display name

Writing Your First Post

Click New Post or navigate to the post creation page
Enter a title
Write your content in Markdown
Click Publish or Save as Draft

Writing with Mataroa

Markdown Support

Mataroa uses Markdown for formatting:

# Heading 1
## Heading 2
### Heading 3

**Bold text** and *italic text*

- Bullet lists
- Are easy

1. Numbered lists
2. Work too

> Blockquotes for emphasis

`Inline code` and:

Code blocks for longer code

[Links](https://example.com)

![Images](https://example.com/image.jpg)

Post Management

Drafts: Save posts as drafts before publishing

Scheduling: Some configurations allow scheduling future posts

Editing: Update posts at any time

Deleting: Remove posts when needed

URL Structure

Mataroa generates clean URLs:

Posts: yourblog.com/blog/post-slug/
About: yourblog.com/about/
Archive: yourblog.com/archive/

RSS and Subscriptions

RSS Feed

Mataroa automatically generates RSS feeds:

Main feed: yourblog.com/rss/
Subscribers can use any RSS reader

Email Newsletters

If configured with SMTP:

Readers can subscribe to email updates
New posts trigger email notifications
Manage subscribers in settings

Custom Domain Setup

Configuring Your Domain

Add your custom domain in Mataroa settings
Update ALLOWED_HOSTS environment variable to include your domain
Configure DNS records:
- CNAME record pointing to your Klutch.sh app
- Or A record if using IP address

SSL for Custom Domains

Klutch.sh handles SSL certificates automatically for custom domains.

Theming and Customization

CSS Customization

Mataroa allows custom CSS:

Go to Settings > CSS
Add your custom styles
Save and refresh to see changes

Example Custom Styles

/* Change link color */
a {
  color: #0066cc;
}

/* Adjust post width */
.post-content {
  max-width: 700px;
}

/* Custom font */
body {
  font-family: Georgia, serif;
}

Production Best Practices

Security Recommendations

Strong Secret Key: Use a long, random secret key
HTTPS Only: Klutch.sh provides this automatically
Regular Updates: Keep Mataroa updated
Backup Posts: Regular exports of your content

Backup Strategy

Export your posts regularly:

Go to Settings > Export
Download your posts in Markdown format
Store backups securely

Performance

Mataroa is inherently fast:

No JavaScript to load
Minimal CSS
Simple HTML structure
Database optimization for reads

Troubleshooting Common Issues

Cannot Access Blog

Symptoms: 500 errors or blank page.

Solutions:

Verify DATABASE_URL is correct
Check ALLOWED_HOSTS includes your domain
Verify SECRET_KEY is set
Run database migrations

CSS Not Loading

Symptoms: Page appears unstyled.

Solutions:

Check static files are being served
Verify browser isn’t blocking resources
Clear browser cache

Email Not Sending

Symptoms: Subscribers don’t receive notifications.

Solutions:

Verify SMTP credentials
Check email host allows your connection
Test SMTP connection independently
Check spam folders

Post Formatting Issues

Symptoms: Markdown not rendering correctly.

Solutions:

Verify Markdown syntax
Check for unsupported Markdown extensions
Preview before publishing

Alternative Blogging Platforms

If Mataroa doesn’t fit your needs, consider:

Ghost: Feature-rich modern blogging
WriteFreely: Minimalist, federated blogging
WordPress: Full-featured CMS
Hugo/Jekyll: Static site generators

Additional Resources

Conclusion

Deploying Mataroa on Klutch.sh gives you a minimalist, distraction-free blogging platform that focuses on what matters: your writing. With no trackers, no JavaScript, and no unnecessary features, Mataroa provides a pure writing and reading experience.

The combination of Mataroa’s simplicity and Klutch.sh’s reliable hosting means your blog is always available, loads instantly, and respects your readers’ privacy. Whether you’re starting a personal blog, a professional publication, or just a place to share your thoughts, Mataroa provides the perfect canvas.

Embrace minimalism and own your content with a self-hosted blog that puts writing first.