Mailpile v1 - Deployment & Usage Guide (Legacy)

⚠️ Important Notice: Development on this codebase (Mailpile v1) has halted. This guide is for running the legacy version only, primarily to access existing Mailpile v1 data. For new installations, consider the Python 3 rewrite or alternative email clients.

The recommended and simplest way to run Mailpile v1 is using the official legacy Docker images.

1. Prerequisites

For Docker (Recommended)

• Docker or Docker Compose installed on your system.
• A supported IMAP email account (Gmail, Fastmail, generic IMAP, etc.) for importing mail.
• (Optional) A PGP key if you wish to use encryption features.

For Native Installation (Not Recommended)

• Python 2.7 (Mailpile v1 is not compatible with Python 3).
• pip for Python 2.7.
• GPG (GnuPG) command-line tool installed and in your PATH.
• System dependencies for Python packages (e.g., build-essential, libssl-dev, libffi-dev on Debian/Ubuntu).
• A modern web browser.

2. Installation

Option A: Using Docker (Strongly Recommended)

1. Pull the latest legacy Docker image:

   docker pull mailpile/mailpile:v1
   

2. Create a persistent volume for Mailpile's data (so your configuration and mail index survive container restarts):

   docker volume create mailpile-data
   

Option B: Native Installation (Advanced/Unsupported)

1. Clone the repository:

   git clone https://github.com/mailpile/Mailpile.git
   cd Mailpile
   

2. Install Python dependencies. The project uses a requirements.txt or setup.py:

   # Use pip for Python 2.7
   pip install -r requirements.txt
   # or
   python setup.py develop
   

   Note: Resolving dependencies for an unmaintained Python 2 project can be difficult.

3. Configuration

Docker Deployment

Configuration is handled automatically on first run. The container will generate a new configuration and admin password.

• Data Persistence: The Docker volume mailpile-data stores all configuration, indexes, and downloaded mail.
• Initial Setup: On first access, you will be prompted to create an admin password via the web UI.
• Custom Configuration: To pre-configure settings (like default IMAP sources), you can mount a custom configuration file. See the Mailpile-v1-Docker repository for advanced options.

Native Installation

1. Initialize the application (this creates a ~/.mailpile directory by default):

   python mailpile.py
   

2. The first time you run it, Mailpile will open in your default web browser and guide you through the initial setup wizard, including:
   • Creating an admin password.
   • Configuring your primary email account (IMAP/POP3 settings).
   • Setting up PGP keys (optional but recommended).

4. Build & Run

Docker (Production/Development)

Run the container, mapping ports and volumes:

docker run -d \
  --name mailpile \
  -p 33411:33411 \
  -p 33411:33411/udp \
  -v mailpile-data:/var/mailpile \
  mailpile/mailpile:v1

• -p 33411:33411: Exposes the web interface on port 33411 of your host machine.
• -v mailpile-data:/var/mailpile: Mounts the persistent Docker volume.
• Access the web UI at: http://localhost:33411

To view logs:

docker logs -f mailpile

To stop and remove the container (data in volume remains):

docker stop mailpile && docker rm mailpile

Native (Development Only)

Run the development server:

cd Mailpile
python mailpile.py

This will start the web server (typically on http://localhost:33411) and open your browser. The process runs in the foreground.

5. Deployment

Recommended Platform: Docker on a VPS/Server

Given the age and complexity of the stack, deploying via Docker on a Linux VPS (Ubuntu, Debian, CentOS) is the most reliable method.

1. Server Setup: Install Docker on your server.
2. Run Container: Use the docker run command from section 4, but bind to a public interface if needed:

   docker run -d \
     --name mailpile \
     --restart unless-stopped \
     -p 80:33411 \
     -p 443:33411 \
     -v /path/on/host/mailpile-data:/var/mailpile \
     mailpile/mailpile:v1
   

   • Security Note: Exposing port 80/443 directly is for example only. In production, use a reverse proxy (like Nginx or Traefik) to handle TLS termination and provide a standard HTTPS endpoint.
3. Reverse Proxy (Nginx) Example: Configure Nginx to proxy https://mail.yourdomain.com to http://localhost:33411.
4. Firewall: Ensure your firewall allows traffic on the public port (80/443).

Alternative: Systemd Service (Native)

If you must run natively, create a systemd service file (/etc/systemd/system/mailpile.service):

[Unit]
Description=Mailpile Email Client
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/opt/Mailpile
ExecStart=/usr/bin/python /opt/Mailpile/mailpile.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then: sudo systemctl enable --now mailpile

6. Troubleshooting

Common Docker Issues

• Port Already in Use: Change the host port mapping (-p 33412:33411).
• Permission Denied on Volume: Ensure the Docker volume is accessible by the container's user (usually UID 1000). You may need to chown the host directory if using a bind mount instead of a named volume.
• Cannot Access Web UI: Check the container is running (docker ps), and verify firewall/security group rules allow traffic to the host port.
• View Detailed Logs: docker logs mailpile will show startup errors, configuration issues, or indexing problems.

Common Native/General Issues

• Python 2.7 Not Found: Mailpile v1 requires Python 2.7. Ensure python --version reports 2.7.x.
• Missing GPG: Install GnuPG (sudo apt install gnupg or sudo yum install gnupg).
• Importing Mail Fails: Verify your IMAP/POP3 credentials and server settings are correct. Check the Mailpile logs (in ~/.mailpile/logs/ or Docker logs) for specific authentication errors.
• Search/Indexing is Slow: Initial indexing of large mailboxes can be resource-intensive. The RESCAN_BATCH_SIZE in mailpile/mail_source/__init__.py (default 200) controls batch size. This is a legacy limitation.
• "Development has halted" Message: This is expected. You are running an unmaintained legacy version. Do not expect new features or security updates.

Data & Migration

• Backup: Regularly backup your Mailpile data directory (~/.mailpile/ or the Docker volume mailpile-data). This contains your configuration, indexes, and (optionally) cached mail.
• Accessing Legacy Data: If you need to extract mail from a Mailpile v1 installation, you can use the Docker image to run the client, access the web UI, and use the "Export" function to download messages in standard formats (EML, MBOX).
• Migration to Newer Systems: There is no official upgrade path from v1 to the Python 3 rewrite. Export your mail and contacts manually if needed.

Getting Help

• The original community forums and issue trackers are largely archived.
• For critical issues with the Docker image, check the Mailpile-v1-Docker repository.
• Consider migrating to a maintained email client if you require ongoing support and security updates.