Deploying phpList

Introduction

phpList is a powerful open-source email marketing platform used by organizations worldwide to send newsletters, announcements, and marketing campaigns. With over 25 years of development, phpList has evolved into a mature, feature-rich solution that handles everything from small mailing lists to enterprise-scale email campaigns.

Built with PHP and supporting MySQL or PostgreSQL databases, phpList provides comprehensive subscriber management, campaign creation, delivery tracking, and analytics. The platform processes billions of emails annually and offers an alternative to expensive commercial email marketing services.

Key highlights of phpList:

• Unlimited Subscribers: No artificial limits on list size or email volume
• Campaign Management: Create, schedule, and send email campaigns with ease
• Subscriber Segmentation: Target specific audiences with attributes and segments
• Template System: Design professional emails with customizable templates
• Bounce Processing: Automatic handling of bounced emails and invalid addresses
• Click Tracking: Monitor link clicks and engagement metrics
• Open Rate Tracking: Track email opens with invisible tracking pixels
• A/B Testing: Test subject lines and content for optimal engagement
• REST API: Integrate with external systems and automate workflows
• GDPR Compliance: Built-in tools for consent management and data privacy
• Plugin System: Extend functionality with community plugins

This guide walks through deploying phpList on Klutch.sh using Docker, configuring the email infrastructure, and setting up the platform for production newsletter campaigns.

Why Deploy phpList on Klutch.sh

Deploying phpList on Klutch.sh provides several advantages:

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

Persistent Storage: Attach persistent volumes for the database, attachments, and uploaded content. Your subscriber lists and campaign history survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure subscriber management and form submissions.

GitHub Integration: Connect your configuration repository directly from GitHub for version-controlled deployments.

Scalable Resources: Allocate CPU and memory based on list size and sending volume.

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

Custom Domains: Assign a custom domain for professional branding on subscription forms and email links.

Always-On Availability: Your email infrastructure remains accessible for subscriber signups and campaign management.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your phpList configuration
• Basic familiarity with Docker and containerization concepts
• A MySQL or PostgreSQL database (can be hosted separately or on Klutch.sh)
• SMTP credentials for sending emails (SendGrid, Mailgun, Amazon SES, etc.)
• (Optional) A custom domain for your phpList instance

Understanding phpList Architecture

phpList uses a traditional LAMP stack architecture:

Web Interface: PHP-based admin panel for campaign creation, subscriber management, and configuration. Built for reliability and ease of use.

Database: MySQL or PostgreSQL stores subscribers, campaigns, templates, and tracking data. Proper indexing is critical for large lists.

Message Queue: Campaigns are processed through a queue system that handles rate limiting and retry logic for reliable delivery.

Bounce Handler: Separate process for receiving and processing bounce notifications to maintain list hygiene.

SMTP Integration: Connects to external SMTP services or local mail servers for actual email delivery.

Preparing Your Repository

To deploy phpList on Klutch.sh, create a GitHub repository with your Dockerfile and configuration.

Repository Structure

phplist-deploy/
├── Dockerfile
├── README.md
├── .dockerignore
└── config/
    └── config.php

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM phplist/phplist:latest

# Set environment variables
ENV PHPLIST_DATABASE_HOST=${PHPLIST_DATABASE_HOST}
ENV PHPLIST_DATABASE_NAME=${PHPLIST_DATABASE_NAME:-phplist}
ENV PHPLIST_DATABASE_USER=${PHPLIST_DATABASE_USER}
ENV PHPLIST_DATABASE_PASSWORD=${PHPLIST_DATABASE_PASSWORD}

# SMTP Configuration
ENV PHPMAILERHOST=${PHPMAILERHOST}
ENV PHPMAILERPORT=${PHPMAILERPORT:-587}
ENV PHPMAILERUSER=${PHPMAILERUSER}
ENV PHPMAILERPASSWORD=${PHPMAILERPASSWORD}

# Application settings
ENV PHPLIST_ADMIN_URL=${PHPLIST_ADMIN_URL}

# Create necessary directories
RUN mkdir -p /var/www/html/lists/uploadimages \
    && mkdir -p /var/www/html/lists/attachments \
    && chown -R www-data:www-data /var/www/html/lists

# Expose web port
EXPOSE 80

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

Creating Custom Configuration

Create config/config.php with your settings:

<?php
// Database configuration
$database_host = getenv('PHPLIST_DATABASE_HOST') ?: 'localhost';
$database_name = getenv('PHPLIST_DATABASE_NAME') ?: 'phplist';
$database_user = getenv('PHPLIST_DATABASE_USER') ?: 'phplist';
$database_password = getenv('PHPLIST_DATABASE_PASSWORD') ?: '';

// Admin interface settings
$pageroot = '/lists';
$adminpages = $pageroot . '/admin';

// SMTP settings
define('PHPMAILERHOST', getenv('PHPMAILERHOST') ?: '');
define('PHPMAILERPORT', getenv('PHPMAILERPORT') ?: 587);
define('PHPMAILER_SECURE', 'tls');
define('PHPMAILERUSER', getenv('PHPMAILERUSER') ?: '');
define('PHPMAILERPASSWORD', getenv('PHPMAILERPASSWORD') ?: '');

// Batch sending configuration
define('MAILQUEUE_BATCH_SIZE', 500);
define('MAILQUEUE_BATCH_PERIOD', 3600);
define('MAILQUEUE_THROTTLE', 1);

// Security settings
define('ASKFORPASSWORD', 1);
define('ENCRYPTION_KEY', getenv('PHPLIST_ENCRYPTION_KEY') ?: '');

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
PHPLIST_DATABASE_HOST	Yes	localhost	Database hostname
PHPLIST_DATABASE_NAME	No	phplist	Database name
PHPLIST_DATABASE_USER	Yes	-	Database username
PHPLIST_DATABASE_PASSWORD	Yes	-	Database password
PHPMAILERHOST	Yes	-	SMTP server hostname
PHPMAILERPORT	No	587	SMTP port
PHPMAILERUSER	Yes	-	SMTP username
PHPMAILERPASSWORD	Yes	-	SMTP password
PHPLIST_ENCRYPTION_KEY	Yes	-	Key for encrypting sensitive data

Deploying phpList on Klutch.sh

Set Up Your Database

Before deploying phpList, provision a MySQL or PostgreSQL database. You can use a managed database service or deploy one on Klutch.sh.

Generate Encryption Key

Generate a secure encryption key:

openssl rand -base64 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore config/ README.md
git commit -m "Initial phpList deployment configuration"
git remote add origin https://github.com/yourusername/phplist-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 “phplist” 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 phpList Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
PHPLIST_DATABASE_HOST	Your database hostname
PHPLIST_DATABASE_NAME	phplist
PHPLIST_DATABASE_USER	Your database username
PHPLIST_DATABASE_PASSWORD	Your database password
PHPMAILERHOST	Your SMTP server (e.g., smtp.sendgrid.net)
PHPMAILERPORT	587
PHPMAILERUSER	Your SMTP username
PHPMAILERPASSWORD	Your SMTP password
PHPLIST_ENCRYPTION_KEY	Your generated encryption key

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/www/html/lists/uploadimages	5 GB	Uploaded images for campaigns
/var/www/html/lists/attachments	10 GB	Email attachments

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and deploy your phpList instance.

Access phpList Admin

Once deployment completes, access the admin interface at https://your-app-name.klutch.sh/lists/admin/. Complete the initial setup wizard.

Initial Setup and Configuration

Running the Installer

On first access:

1. Navigate to /lists/admin/
2. The installer will check prerequisites
3. Initialize the database tables
4. Create your admin account
5. Configure basic settings

Creating Your First List

Set up a subscriber list:

1. Go to Subscribers → Lists
2. Click Add a List
3. Enter list name and description
4. Configure subscription options
5. Save the list

Creating a Subscribe Page

Enable public subscriptions:

1. Go to Config → Subscribe Pages
2. Create a new subscribe page
3. Select which lists users can subscribe to
4. Customize the form appearance
5. Get the embed code or URL

Creating a Campaign

Send your first newsletter:

1. Go to Campaigns → Send a Campaign
2. Choose a template or start from scratch
3. Compose your email content
4. Select target lists
5. Preview and test
6. Schedule or send immediately

SMTP Configuration Options

SendGrid

PHPMAILERHOST=smtp.sendgrid.net
PHPMAILERPORT=587
PHPMAILERUSER=apikey
PHPMAILERPASSWORD=your-sendgrid-api-key

Mailgun

PHPMAILERHOST=smtp.mailgun.org
PHPMAILERPORT=587
PHPMAILERUSER=postmaster@your-domain.mailgun.org
PHPMAILERPASSWORD=your-mailgun-password

Amazon SES

PHPMAILERHOST=email-smtp.us-east-1.amazonaws.com
PHPMAILERPORT=587
PHPMAILERUSER=your-ses-smtp-username
PHPMAILERPASSWORD=your-ses-smtp-password

Troubleshooting Common Issues

Database Connection Errors

• Verify database credentials are correct
• Ensure database server is accessible
• Check that database exists and user has permissions

Emails Not Sending

• Verify SMTP credentials
• Check SMTP server allows connections
• Review phpList logs for delivery errors
• Test SMTP connection independently

Slow Sending Performance

• Adjust batch size and throttling settings
• Ensure database is properly indexed
• Consider dedicated SMTP service for high volume

Additional Resources

• Official phpList Website
• phpList Documentation
• phpList Community Forums
• phpList GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying phpList on Klutch.sh provides a powerful, self-hosted email marketing platform without the high costs of commercial solutions. The combination of phpList’s comprehensive features and Klutch.sh’s deployment simplicity enables effective email marketing with complete control over your data and infrastructure.

Whether you’re managing a small newsletter or running large-scale email campaigns, phpList on Klutch.sh delivers the tools needed for professional email marketing while keeping costs predictable and data private.