How To Install PHPList on Debian 12

PHPList is a powerful open-source newsletter management system that enables efficient email campaign management for websites, businesses, and organizations. If you’re looking for a self-hosted email marketing solution, PHPList combined with Debian 12’s stability creates an ideal platform for managing your subscriber lists and campaigns. This comprehensive guide will walk you through the complete installation process, from setting up prerequisites to configuring and optimizing your PHPList installation.

Prerequisites

Before beginning the PHPList installation process on your Debian 12 server, you need to ensure several requirements are met:

System Requirements

• A Debian 12 server with root or sudo privileges
• Minimum 1GB RAM (2GB recommended for optimal performance)
• At least 10GB of available disk space
• Static IP address for your server

Domain Configuration
While not strictly required, having a properly configured domain name pointing to your server is recommended for production environments. This facilitates subscriber access to your forms and simplifies system management.

Technical Knowledge
This guide assumes basic familiarity with Linux command-line operations, including using text editors like nano or vim. You should also understand fundamental web server concepts and database management.

Backup Procedures
If installing PHPList on an existing server, create a complete backup of your system before proceeding. This ensures you can restore your data if issues arise during installation.

Understanding PHPList

PHPList serves as an open-source newsletter manager that allows you to create, manage, and send email communications to subscriber lists. Since its initial release, it has become one of the most widely used self-hosted email marketing platforms.

Key Features:

• List management with subscriber segmentation capabilities
• HTML and text-based campaign creation
• Scheduled email delivery
• Comprehensive tracking and statistics
• Bounce management
• CMS integration options
• Multiple administrator support

PHPList uses a LAMP (Linux, Apache, MySQL, PHP) stack architecture. It stores all data in a MySQL/MariaDB database, with application logic written in PHP, while the web interface is served through Apache or Nginx.

Step 1: Update Your System

Always begin by ensuring your Debian system is fully updated to prevent compatibility issues and incorporate the latest security patches.

Open a terminal and run:

sudo apt update
sudo apt upgrade -y

The first command refreshes package lists from repositories, while the second upgrades all installed packages to their latest versions. The -y flag automatically confirms the upgrade process.

Step 2: Installing LAMP Stack

PHPList requires a complete LAMP stack (Linux, Apache, MySQL, PHP) to function properly.

Installing Apache Web Server

Apache will serve your PHPList application:

sudo apt install apache2 apache2-utils -y

Enable Apache to start automatically at system boot:

sudo systemctl enable apache2

Verify Apache is running correctly:

sudo systemctl status apache2

You should see output indicating the service is active. Test Apache by opening your server’s IP address in a web browser – you should see the default Apache page.

Installing MariaDB

MariaDB serves as the database server for PHPList:

sudo apt install mariadb-server mariadb-client -y

After installation, secure your MariaDB setup:

sudo mysql_secure_installation

This security script will prompt you to:

• Set a root password
• Remove anonymous users
• Disallow root login remotely
• Remove test database and access
• Reload privilege tables

Answer “Y” (yes) to all prompts to enhance your database security.

Installing PHP

Install PHP and required extensions:

sudo apt install php libapache2-mod-php php-mysql php-curl php-gd php-intl php-mbstring php-xml php-zip -y

Restart Apache to load the PHP module:

sudo systemctl restart apache2

Step 3: Creating a MySQL Database for PHPList

Now create a dedicated database for PHPList:

sudo mysql -u root -p

Enter your MariaDB root password when prompted. Then create a database and user:

CREATE DATABASE phplist_db;
CREATE USER 'phplist_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL ON phplist_db.* TO 'phplist_user'@'localhost';
FLUSH PRIVILEGES;
exit

Replace ‘your_secure_password’ with a strong password. Note down the database name, username, and password as you’ll need them later.

Step 4: Downloading PHPList

Download the latest PHPList version from the official website or SourceForge:

cd /tmp
wget https://sourceforge.net/projects/phplist/files/latest/download -O phplist.zip

Install unzip if not already available:

sudo apt install unzip -y

Extract the downloaded file:

unzip phplist.zip

This creates a directory named “phplist-x.y.z” (where x.y.z represents the version number).

Step 5: Configuring Web Server

Now configure Apache to serve PHPList.

Setting Up the Web Directory

Create a directory for PHPList in Apache’s web directory:

sudo mkdir -p /var/www/html/list

Move the extracted PHPList files:

sudo cp -r /tmp/phplist-*/* /var/www/html/list/

Setting Proper Permissions

Set appropriate permissions:

sudo chown -R www-data:www-data /var/www/html/list
sudo chmod -R 755 /var/www/html/list

For directories needing write access:

sudo chmod -R 777 /var/www/html/list/uploads
sudo chmod -R 777 /var/www/html/list/lists

Step 6: PHPList File Preparation

Before configuration, prepare essential files:

Navigate to the config directory:

cd /var/www/html/list/config

Create a configuration file from the example:

sudo cp config_extended.php config.php

Ensure necessary directories are writable:

sudo chmod -R 777 /var/www/html/list/tmp
sudo chmod -R 777 /var/www/html/list/attachments

Step 7: Configuring PHPList

Edit the configuration file to establish database connections and other settings:

sudo nano /var/www/html/list/config/config.php

Update the following settings:

// Database connection settings
$database_name = "phplist_db";
$database_user = "phplist_user";
$database_password = "your_secure_password";

// The base URL of your PHPList installation
$pageroot = '/list';
$adminpages = '/list/admin';

// Set test mode to 0 for production
define("TEST", 0);

Replace ‘your_secure_password’ with the password you created earlier. Save and close the file.

Step 8: Running the Installation Process

Now complete the web-based installation process:

Open your browser and navigate to:

http://your_server_ip/list/admin/

You’ll see the PHPList login page. Default credentials are:

• Username: admin
• Password: phplist

After logging in, click “initialise database” to create necessary tables. Once initialization completes, click “phpList setup” to continue.

Step 9: Post-Installation Configuration

After installation, configure these important settings:

Change Admin Password

First, change the default password:

1. Click “admin” in the top menu
2. Select “change password”
3. Enter a strong new password

Take PHPList Out of Test Mode

If you didn’t already edit the config.php file to disable test mode:

1. Edit config.php
2. Change define("TEST", 1); to define("TEST", 0);
3. Save the file

Update Page Root

Ensure your page root settings match your installation directory:

1. In config.php, confirm these settings:

   $pageroot = '/list';
   $adminpages = '/list/admin';

2. Save changes

System Settings

Navigate to “Config” to configure:

• Domain for message tracking
• From email address
• Admin email address
• Test message recipients

Step 10: Setting Up Cron Jobs

PHPList requires cron jobs for queue processing and maintenance tasks:

sudo crontab -u www-data -e

Add these lines:

# Process PHPList message queue every 5 minutes
*/5 * * * * php /var/www/html/list/admin/index.php -p processqueue > /dev/null

# Process bounces hourly
0 * * * * php /var/www/html/list/admin/index.php -p processbounces > /dev/null

# Daily maintenance
0 0 * * * php /var/www/html/list/admin/index.php -p maintenance > /dev/null

Save and close the file.

Step 11: Rate Limiting Email Sending

To prevent being flagged as spam and comply with hosting provider limits, configure email rate limiting:

Edit config.php:

sudo nano /var/www/html/list/config/config.php

Add these settings:

// Number of emails per batch
define("MAILQUEUE_BATCH_SIZE", 17);

// Seconds between batches
define("MAILQUEUE_BATCH_PERIOD", 300);

This configuration sends 17 emails every 5 minutes (300 seconds), equating to approximately 204 emails per hour. Adjust these values according to your hosting provider’s limits.

Step 12: Testing Your Installation

Now test your PHPList installation:

Create a Test List

1. Log in to the PHPList admin interface
2. Click “Lists” in the top menu
3. Click “Add a list” and complete the required information
4. Save the list

Add Test Subscribers

1. Click “Subscribers” in the top menu
2. Click “Add subscriber” and enter details
3. Assign the subscriber to your test list
4. Save the subscriber

Send a Test Campaign

1. Click “Campaigns” in the top menu
2. Click “Send a campaign” and enter subject and content
3. Select your test list
4. Schedule and send the campaign

Monitor the process to ensure emails send correctly. When sending to multiple recipients, PHPList will display a progress screen showing batch limits and timing information.

Security Best Practices

Securing your PHPList installation protects subscriber data and prevents unauthorized access:

Regular Updates

Keep PHPList and system components updated:

sudo apt update
sudo apt upgrade -y

Regularly check for PHPList updates on the official website.

File Permissions

Verify file permissions are set correctly:

sudo find /var/www/html/list -type d -exec chmod 755 {} \;
sudo find /var/www/html/list -type f -exec chmod 644 {} \;

Maintain write access for specific directories:

sudo chmod -R 777 /var/www/html/list/tmp
sudo chmod -R 777 /var/www/html/list/attachments
sudo chmod -R 777 /var/www/html/list/uploads
sudo chmod -R 777 /var/www/html/list/lists

Firewall Configuration

Configure a firewall to restrict server access:

sudo apt install ufw -y
sudo ufw allow SSH
sudo ufw allow HTTP
sudo ufw allow HTTPS
sudo ufw enable

SSL/TLS Certificate

Secure your installation with an SSL/TLS certificate using Let’s Encrypt:

sudo apt install certbot python3-certbot-apache -y
sudo certbot --apache -d yourdomain.com

Troubleshooting Common Issues

Despite careful installation, issues may arise. Here are solutions to common problems:

Database Connection Issues

• Verify the database server is running: sudo systemctl status mariadb
• Confirm database credentials in config.php are correct
• Check that your database and user exist with proper privileges

Email Sending Problems

• Ensure cron jobs are set up correctly: sudo crontab -u www-data -l
• Verify email configuration in PHPList settings
• Check mail logs: sudo tail -f /var/log/mail.log

Permission Issues

• Ensure web server has necessary permissions
• Verify required directories are writable
• Check Apache error logs for details: sudo tail -f /var/log/apache2/error.log

Missing Tables

If you see “table doesn’t exist” errors:

1. Return to admin interface
2. Click “initialise database” again
3. Confirm all tables are created successfully

PHPList Maintenance and Upgrades

To ensure optimal performance and security:

Regular Backups

Create regular database backups:

mysqldump -u root -p phplist_db > phplist_backup_$(date +%Y%m%d).sql

Database Optimization

Periodically optimize the database:

mysql -u root -p -e "OPTIMIZE TABLE phplist_*" phplist_db

Version Updates

When upgrading PHPList:

1. Backup your database and files
2. Download the new version
3. Replace files, preserving your config.php
4. Run database updates from the admin interface

Congratulations! You have successfully installed PHPList. Thanks for using this tutorial for installing PHPList on the Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official PHPList website.