Skip to content

Installation and Setup

Jump to bottom
Tyler Hatfield edited this page Jul 13, 2026 · 1 revision

Installation & Setup

Before running PolyPress, ensure your server meets the minimal hardware and networking prerequisites.

📋 System Requirements

1. Hardware

PolyPress is lightweight, using zero-configuration SQLite storage:

  • Processor: 1 CPU core.
  • Memory (RAM): 512 MB minimum (1 GB recommended).
  • Disk Space: Less than 100 MB for base files, plus storage for subscriber lists.

2. Networking & Ports

  • Dashboard Console (Port 8000): Interface binding port.
  • Let's Encrypt SSL (Port 80): Publicly reachable if using the built-in Let's Encrypt GUI Acme challenge.
  • Outbound MTA (Port 25): Egress port 25 must be unblocked by your hosting provider if you plan to use Direct Send Mode (internal MTA). If port 25 is blocked, configure an external SMTP Relay (like SendGrid, Resend, or SES) on port 587 or 465.

🛠️ Deploying PolyPress

1. Automated Installation (Debian/Ubuntu)

Run the bootstrap installer script to check for dependencies, build a Python virtual environment, and install package dependencies:

./install.sh

To run the Uvicorn web server manually:

source venv/bin/activate
cd backend
uvicorn main:app --host 0.0.0.0 --port 8000

2. Docker & Docker Compose (Recommended)

Launch the services in a clean container environment:

docker compose up -d

3. Deploying via Portainer Stacks

  1. Navigate to Stacks -> Add stack.
  2. Paste the contents of your docker-compose.yml into the editor.
  3. Click Deploy the stack.

Warning

Portainer Relative Bind Mounts: Relative paths (like ./data or ./backups) in Portainer resolve relative to Portainer's internal compose directory. It is highly recommended to change relative paths in your stack config to absolute paths (e.g. /home/ubuntu/polypress/data:/app/data) to make your assets and databases easily accessible on your host machine.

🧙 First-Open Onboarding Setup Wizard

When you open http://localhost:8000 in your browser for the first time, PolyPress will guide you through an interactive setup wizard:

  1. Branding Name: Set the custom name of your PolyPress installation.
  2. Super Admin Credentials: Set the email and password for your global host administrator account.
  3. Email Transports: Set up direct MTA sending with DKIM or configure an SMTP relay.
  4. Bounce Mailbox: Configure IMAP connection details to automatically fetch and process return-path emails.

Once complete, your credentials are saved, database schemas are initialized, and you are automatically redirected to the dashboard.

Clone this wiki locally