Setup guide

Setting up PeepEn.

About half an hour on shared hosting. You need your hosting login, your mail server settings (IMAP and SMTP), and a license key.

Shared hosting

What you need

Hosting with PHP 8.1 or newer and the pdo_sqlite, sodium, mbstring, iconv, openssl, dom and curl extensions. Most cPanel hosts have them; setup checks for you.
HTTPS on the address PeepEn will use (cPanel's free AutoSSL is fine).
Your mail server settings: IMAP and SMTP host names, ports and security. Your host's help pages list them.
Cron jobs (cPanel → Cron Jobs), so mail is checked when nobody has PeepEn open.

1. Get a license key

Make an account with your company name and confirm your email. The key appears on the page and in your inbox. Every install needs one, including the free plan.

Download the newest peepen-<version>.zip from your account.

2. Upload

In cPanel → File Manager, upload the zip into public_html and extract it into a folder, for example public_html/mail. Or use a subdomain like mail.yourcompany.com pointed at that folder.

3. Run setup

Open the address, for example https://yourcompany.com/mail/. Setup starts on its own:

License key. It activates the key for this install and proves the install is yours.
Checks. PHP and its extensions.
Data folder. Setup suggests one next to public_html, never inside it. It holds the database and the key that encrypts mailbox passwords.
The Owner. Name, username, a password of at least 10 characters, an authenticator app (scan the QR code), and 10 recovery codes. Print or save them.
Company and mail server. Entered once and tested with a real login; every mailbox you add later uses it.

peep.moe can't be reached from your hosting? Setup asks for the code in PEEPEN-SETUP-CODE.php, which it wrote into the folder. It still needs the key to activate before it finishes.

4. The cron job

Setup shows the exact line for your account. In cPanel → Cron Jobs, add it to run every minute:

* * * * * php /home/USER/public_html/mail/bin/peepctl.php tick

It checks every mailbox, runs rules and out-of-office replies, and sends reminders. New mail shows within a minute. Setup turns green when it sees the first run.

5. Add people

Admin center → People → Add person: name, username, groups, and their mailbox with its password (or let them type it at first sign-in). PeepEn shows a setup code (8 characters, good for 72 hours) and a printable welcome sheet. They open the address, choose I have a setup code, and pick their PIN.

Then Admin center → Groups: make a group, give it shared mailboxes (read, send or manage) and a group calendar, and add people to it.

VPS

Console install

On a VPS with Apache, unzip into a folder Apache serves and either use the browser setup above, or the console (Rocky / RHEL shown; on Debian or Ubuntu use --user=www-data):

php /var/www/peepen/bin/peepctl.php check

php /var/www/peepen/bin/peepctl.php init --data=/var/lib/peepen --user=apache

With SELinux on, give the data folder a writable context:

semanage fcontext -a -t httpd_sys_rw_content_t "/var/lib/peepen(/.*)?" && restorecon -R /var/lib/peepen

sudo -u apache php /var/www/peepen/bin/peepctl.php owner boss --name="Your Name" [email protected]

owner prints a setup code: open the site, choose I have a setup code, pick a password and authenticator, then enter the license key under Admin → License. AllowOverride All must be on for the folder so its .htaccess files protect lib/, bin/ and config.php.

Push service

On a VPS, run the push service instead of cron: it holds one connection per mailbox, so new mail shows within seconds (tested at 280 mailboxes in about 42 MB).

dnf install -y php-process

sudo tee /etc/systemd/system/peepen.service >/dev/null <<'EOF'
[Unit]
Description=PeepEn push service (peepd)
After=network-online.target

[Service]
User=apache
WorkingDirectory=/var/www/peepen
ExecStart=/usr/bin/php bin/peepd.php
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload && sudo systemctl enable --now peepen && systemctl status peepen --no-pager

Afterwards

Phones

Each person adds their phone under Settings → Phones → Add, which gives that phone its own password. On iPhone or iPad, scan the QR code with the camera within 15 minutes and install the profile. On Android, use DAVx⁵ with the server address, username and password shown. The phone gets their calendar, shared calendars, rooms and the company directory.

Peep for Windows

Install Peep for Windows from the download page, then link it to your PeepEn address with a username and setup code. The mailboxes and calendars come from the server, so there's nothing to set up on the PC.

Moving from Peep Web

Someone already using Peep Web for themselves can bring their contacts, calendar, tasks, notes, rules and settings: in Peep Web, Settings → Server → Export my data; then in PeepEn, Settings → Import. Importing again later only adds what's new or changed.

Updating

Upload the new zip over the old folder and extract it, replacing files. Keep config.php. The database updates itself on the next visit. On a VPS, restart the push service afterwards: systemctl restart peepen.

Moving to a new server

Copy the data folder to the new server and install PeepEn there. In your account, choose Move to a new server on the key, then enter it under Admin → License on the new install.

Locked out

Who	What to do
Staff	An admin unlocks them or makes a new setup code (Admin → People).
An admin	The Owner does the same for admins.
The Owner, with recovery codes	Use one: it works like a setup code.
The Owner, without them	Create an empty file named `RESET-OWNER` in PeepEn's folder (File Manager or FTP) and open the sign-in page. It becomes `RESET-OWNER-CODE.php` with a one-time code, which proves you control the server.

Still stuck? Write to info@peep.moe.