Deploying Keila

Introduction

Keila is a powerful, open-source, self-hosted newsletter platform that provides a privacy-focused alternative to mainstream email marketing tools like Mailchimp, Buttondown, or ConvertKit. Built with Elixir for reliability and performance, Keila offers all the essential features you need to create, manage, and send professional email newsletters.

With support for multiple email sending services including SMTP, AWS SES, Mailgun, Postmark, and SendGrid, Keila gives you flexibility in how you deliver your campaigns. The intuitive drag-and-drop editor makes creating beautiful emails easy, while powerful segmentation and automation features help you reach the right audience at the right time.

Key highlights of Keila:

• Privacy-Focused: Self-hosted with complete data ownership and GDPR compliance
• Multiple Senders: Connect SMTP, AWS SES, Mailgun, Postmark, or SendGrid
• Drag-and-Drop Editor: Create beautiful emails without coding knowledge
• Contact Management: Import, segment, and manage your subscriber lists
• Campaign Analytics: Track opens, clicks, and engagement metrics
• Forms and Embeds: Create signup forms for your website
• API Access: Integrate with your applications via REST API
• Multi-Project Support: Manage multiple newsletters from one instance
• Template Library: Start with pre-built templates or create your own
• Double Opt-In: Built-in confirmation workflow for subscribers

This guide walks through deploying Keila on Klutch.sh using Docker, configuring email sending services, and setting up your first newsletter.

Why Deploy Keila on Klutch.sh

Deploying Keila on Klutch.sh provides several advantages for newsletter management:

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

Persistent Storage: Attach persistent volumes for your PostgreSQL database, storing all your contacts, campaigns, and analytics data securely.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for professional email marketing and form embeds.

Environment Variable Management: Securely store SMTP credentials and API keys through Klutch.sh’s environment variable system.

Cost-Effective: Self-hosting eliminates per-subscriber fees common with commercial newsletter platforms.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• An email sending service (SMTP server, AWS SES, Mailgun, etc.)
• A PostgreSQL database (can be provisioned on Klutch.sh)

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM pentacent/keila:latest

# Environment variables configured via Klutch.sh dashboard
# SECRET_KEY_BASE - Required for encryption
# DB_URL - PostgreSQL connection string
# URL_HOST - Your domain name
# MAILER_SMTP_* - Email configuration

EXPOSE 4000

Environment Variables Reference

Variable	Required	Description
SECRET_KEY_BASE	Yes	Secret key for encryption (min 64 chars)
DB_URL	Yes	PostgreSQL connection string
URL_HOST	Yes	Your domain without protocol
URL_SCHEMA	No	https (default) or http
PORT	No	HTTP port (default: 4000)
MAILER_SMTP_HOST	Yes	SMTP server hostname
MAILER_SMTP_PORT	No	SMTP port (default: 587)
MAILER_SMTP_USER	Yes	SMTP username
MAILER_SMTP_PASSWORD	Yes	SMTP password

Creating the .dockerignore File

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

Deploying Keila on Klutch.sh

Generate Your Secret Key

Generate a secure secret key for Keila:

openssl rand -base64 64

Save this key securely for the environment variables configuration.

Set Up PostgreSQL Database

Keila requires PostgreSQL. You can:

• Use a managed PostgreSQL service
• Deploy PostgreSQL on Klutch.sh alongside Keila
• Use a cloud database provider

Note your database connection URL in the format: postgres://user:password@host:5432/keila

Push Your Repository to GitHub

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

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

Configure HTTP Traffic

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

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

Set Environment Variables

Variable	Value
SECRET_KEY_BASE	Your generated 64+ character secret
DB_URL	postgres://user:pass@host:5432/keila
URL_HOST	your-app-name.klutch.sh
URL_SCHEMA	https
MAILER_SMTP_HOST	Your SMTP server
MAILER_SMTP_USER	Your SMTP username
MAILER_SMTP_PASSWORD	Your SMTP password

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container and provision HTTPS.

Access Keila

Once deployment completes, access Keila at https://your-app-name.klutch.sh. Create your first account to start building newsletters.

Initial Setup and Configuration

Creating Your Account

On first access:

1. Click Register to create your admin account
2. Confirm your email address (if configured)
3. Log in to access the dashboard

Creating Your First Project

Keila uses projects to organize newsletters:

1. Click Create Project on the dashboard
2. Enter a project name (e.g., “My Newsletter”)
3. Configure project settings and sender details

Setting Up a Sender

Configure your email sending:

1. Navigate to Senders in your project
2. Click New Sender
3. Choose your sending method (SMTP, SES, etc.)
4. Configure credentials and test the connection

Creating Signup Forms

Build your subscriber list:

1. Go to Forms in your project
2. Create a new signup form
3. Customize fields and styling
4. Embed the form on your website

Creating Campaigns

Email Editor

Use the drag-and-drop editor:

1. Navigate to Campaigns > New Campaign
2. Choose a template or start from scratch
3. Add blocks: text, images, buttons, dividers
4. Preview your email on desktop and mobile

Sending Campaigns

When ready to send:

1. Select your target contacts or segments
2. Configure subject line and preview text
3. Schedule or send immediately
4. Monitor delivery and engagement

Production Best Practices

Email Deliverability

• SPF/DKIM/DMARC: Configure email authentication records
• Warm Up: Gradually increase sending volume
• Clean Lists: Remove bounced and unengaged contacts
• Monitor Reputation: Track delivery rates and spam complaints

Database Maintenance

• Regular Backups: Back up your PostgreSQL database
• Monitor Growth: Track database size as contacts grow
• Optimize Queries: Large lists may need index optimization

Troubleshooting Common Issues

Emails Not Sending

Solutions:

• Verify SMTP credentials are correct
• Check sender verification with your email provider
• Review application logs for specific errors
• Test with a simple campaign to a known address

Forms Not Working

Solutions:

• Ensure URL_HOST matches your actual domain
• Check that CORS settings allow your website
• Verify form embed code is correctly placed

Additional Resources

• Keila Website
• Keila Documentation
• Keila GitHub Repository
• Keila Docker Hub
• Klutch.sh Deployments

Conclusion

Deploying Keila on Klutch.sh gives you a powerful, self-hosted newsletter platform with automatic builds, secure HTTPS, and complete data ownership. The combination of Keila’s feature-rich email marketing tools and Klutch.sh’s deployment simplicity means you can focus on growing your audience rather than managing infrastructure.

With support for multiple sending services, beautiful email templates, and comprehensive analytics, Keila on Klutch.sh provides everything you need to run professional email newsletters without the per-subscriber fees of commercial platforms.