Installing peep

peep web

Before you start

These steps are for Rocky Linux, AlmaLinux or RHEL 9 with Apache and PHP-FPM. Run them as root. For Debian or Ubuntu, see the differences at the end.

• PHP 8.1 or newer with pdo_sqlite, mbstring, iconv and openssl. dom and fileinfo are recommended.
• HTTPS on the site you install it under, since your PIN and your mail pass through it.
• Outbound access from the server to your mail providers on ports 993 (IMAP) and 465 or 587 (SMTP).

peep installs as a folder named _mail, so it's served at https://yourdomain.com/_mail/. Its data lives outside the web root in /var/lib/_mail.

1. Unpack and check PHP

Download the package to the server, set DOCROOT to your site's web root, unpack it there and run the built-in check:

cd /root && curl -LO https://peep.moe/downloads/peep-web-1.2.0.tar.gz
DOCROOT=/var/www/html
tar -xzf peep-web-1.2.0.tar.gz -C "$DOCROOT" && php "$DOCROOT/_mail/bin/mailctl.php" check

Every line should end in ok:

PHP 8.1.32  ok
pdo_sqlite  ok
mbstring    ok
iconv       ok
openssl     ok
dom         ok
fileinfo    ok
UTF7-IMAP   ok

If anything says MISSING, install it and run the check again:

dnf install -y php-pdo php-mbstring php-xml && systemctl restart php-fpm && php "$DOCROOT/_mail/bin/mailctl.php" check

2. Create the data folder

This creates the data folder, the encryption key for mailbox passwords, the database and config.php, all owned by Apache:

php "$DOCROOT/_mail/bin/mailctl.php" init --data=/var/lib/_mail --user=apache && ls -la /var/lib/_mail

You should see mail.sqlite, secret.key and tmp/, all owned by apache.

3. Let Apache write the data folder and reach your mail servers

Skip this step if getenforce prints Disabled.

semanage fcontext -a -t httpd_sys_rw_content_t "/var/lib/_mail(/.*)?" && restorecon -Rv /var/lib/_mail && setsebool -P httpd_can_network_connect 1 && getsebool httpd_can_network_connect

It can take 20 to 30 seconds. The last line should be httpd_can_network_connect --> on.

4. Set your PIN

4 to 12 digits. Nothing shows while you type.

php "$DOCROOT/_mail/bin/mailctl.php" setpin && php "$DOCROOT/_mail/bin/mailctl.php" status

The status should show PIN set: yes and Failures: 0 / 5.

5. Start the push service

The push service keeps each mailbox connected, delivers new mail live, runs your rules and keeps unread counts current, even when no browser is open. It starts at boot and restarts itself if it stops.

cat > /etc/systemd/system/mail-push.service <<EOF
[Unit]
Description=peep push service (IMAP IDLE + rules)
After=network-online.target
Wants=network-online.target

[Service]
User=apache
Group=apache
ExecStart=/usr/bin/php $DOCROOT/_mail/bin/maild.php
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now mail-push && sleep 10 && journalctl -u mail-push -n 20 --no-pager

You should see a connected (IDLE push, …) line for each mailbox once you've added some. Right after install there are none yet, so a clean start with no errors is what you want.

6. Open peep and add a mailbox

1. Go to https://yourdomain.com/_mail/ and enter your PIN.
2. Choose Add a mailbox and type the email address. Gmail, AOL, Verizon, Yahoo, iCloud and Outlook fill in their server settings for you.
3. Enter the password. Most providers need an app password here, not your normal one.
4. Click Test & save. peep logs in to IMAP and SMTP before saving.

Then check that the program folders can't be reached from the web. This should print 403:

curl -s -o /dev/null -w '%{http_code}\n' https://yourdomain.com/_mail/lib/bootstrap.php

Debian and Ubuntu

The steps are the same with three differences:

• Packages: apt install php8.1-fpm php8.1-sqlite3 php8.1-mbstring php8.1-xml (use your PHP version's number), then restart php8.1-fpm.
• Apache runs as www-data. Use --user=www-data in step 2 and User=www-data, Group=www-data in the service file.
• Skip step 3. Debian and Ubuntu don't use SELinux by default.

The web root is usually /var/www/html.

Updating peep web

Unpack the new version over the old one and restart the push service. Your settings, mailboxes and PIN are kept: they live in config.php and /var/lib/_mail, which the package doesn't include.

cd /root && curl -LO https://peep.moe/downloads/peep-web-1.2.0.tar.gz
tar -xzf peep-web-1.2.0.tar.gz -C "$DOCROOT" && chown -R apache:apache "$DOCROOT/_mail" && systemctl restart mail-push

Reload the page with Ctrl+F5. The version at the bottom of the sidebar should show the new number.

peep for Windows

Install

1. Download and unzip

   Download peep-0.7.0-windows-portable.zip and unzip it wherever you like, for example C:\Tools\peep or a USB stick.

2. Choose portable or installed

   The zip comes with an empty data folder next to peep.exe. While that folder is there, peep keeps everything in it, so the whole folder can move to another PC. Delete it before the first run to keep your data in %LOCALAPPDATA%\peep instead.

3. Run peep.exe

   If Windows shows "Windows protected your PC", click More info, then Run anyway. That warning appears for programs that haven't built up a download history with Microsoft yet.

First run

1. Choose a PIN. The PC stays unlocked for 14 days after you last used it. Lock it any time with Ctrl+L.
2. Add a mailbox. Type the address; known providers fill in their settings. Use an app password where your provider needs one, then click Test & save.
3. Optional: in Settings, turn on Start with Windows, keep it in the tray when closed, and choose notifications and themes.

Link to your peep server

If you also run peep web, the Windows app can pull mailboxes from it instead of logging in to your mail servers itself.

1. In the Windows app, open Settings → Server → Link to a server…
2. Type your server's address, for example yourdomain.com/_mail/.
3. Enter your web PIN once. The server gives this PC its own key; the PIN isn't stored.
4. Tick the server mailboxes you want on this PC.

Read how linking works for what happens to mailboxes you already have on the PC.

Updating and removing

To update, close peep (also from the tray) and replace peep.exe with the new one. Keep the data folder.

To remove, turn off Start with Windows in Settings, quit from the tray, and delete the peep folder. If you used the installed mode, also delete %LOCALAPPDATA%\peep. If the PC was linked, unlink it first, or remove it from the web app's Settings → Devices afterwards.

Both editions

App passwords

Most big providers refuse your normal password from mail programs. Create an app password in your account's security settings and paste that into peep instead.