Install

imbox runs on one small server that you control. There are four ways to put it there. Pick one, follow its steps, then go on to First run.

If you are not sure, use the one-line installer.

Before you startCopy Anchor Link

All four ways need the same few things.

• A domain name. imbox needs its own address, such as imbox.example.com. Add a DNS A record that points it at your server's public IP address.
• Ports 80 and 443 open on the server, so it can get a certificate and serve the site.
• A size that fits. One CPU and 2 GB of memory is the minimum. Two CPUs and 4 GB is comfortable. Allow 20 GB of disk.
• A place to keep two secrets. The install creates a SESSION_SECRET and a database password. Copy the SESSION_SECRET somewhere safe. It encrypts your saved mailbox passwords, AI keys and two-factor secrets, and without it they can't be read again.

Check that the domain already reaches your server before you go on. The certificate step fails if it doesn't.

dig +short imbox.example.com

The answer should be your server's IP address.

One-line installerCopy Anchor Link

This is for a Debian or Ubuntu server on x86_64. Run it once, as root, on the server:

curl -fsSL https://imbox.lol/install.sh | sudo bash

It checks the server, installs Docker if it is missing, and starts imbox, its PostgreSQL database and Caddy (automatic HTTPS) as one Docker Compose stack in /opt/imbox. It generates the secrets once, sets up a nightly database backup (14 days kept), and waits until imbox answers a health check. Then it prints the address to open. The first visit asks you to create the owner account. Carry on with First run.

With no domain it uses <your-ip>.sslip.io, a free name that points at your server and gets a real certificate, so you can try imbox before you set up DNS. For your own domain, point its DNS A record at the server first, then put the domain after sudo:

curl -fsSL https://imbox.lol/install.sh | sudo IMBOX_DOMAIN=imbox.example.com bash

To update, run the same command again. It keeps your settings and secrets, pulls the newest image and restarts what changed.

Keep a copy of SESSION_SECRET from /opt/imbox/.env. Without it, stored mailbox passwords and keys cannot be read after a restore. The script reads like a short shell program; open https://imbox.lol/install.sh first if you want to see what it does before you run it.

Server scriptCopy Anchor Link

This is for Debian 12 or 13, or Ubuntu 22.04 or 24.04, on x86_64 or arm64. You run it once, as root, on a fresh machine.

1. Run the setupCopy Anchor Link

sudo apt-get update && sudo apt-get install -y git
git clone https://github.com/fr3on/imbox.git
sudo IMBOX_DOMAIN=imbox.example.com bash imbox/deploy/setup.sh

Replace imbox.example.com with your own domain. The script:

1. Installs Node.js 22, PostgreSQL (the version your system ships, 14 or newer works), and Caddy.
2. Creates a imbox system user, a database, and a generated database password.
3. Writes /etc/imbox/imbox.env with a new SESSION_SECRET and your address as APP_URL.
4. Sets up the systemd service, Caddy with automatic HTTPS, and a nightly backup.
5. Opens only SSH, HTTP and HTTPS in the firewall.

It does not put the app on the server yet. That is the next step.

2. Put the app on the serverCopy Anchor Link

Choose the way that suits you. Both end with the same message.

From your computer. This is also how you update later. You need the repository on your computer and an SSH key for the server.

First let your server user switch releases without a password prompt. On the server:

echo 'YOUR_USER ALL=(root) NOPASSWD: /usr/local/bin/imbox-activate' | sudo tee /etc/sudoers.d/imbox-deploy

Then, on your computer:

git clone https://github.com/fr3on/imbox.git && cd imbox
bash deploy/deploy.sh [email protected] ~/.ssh/your-key

On the server, from a release. Download imbox-VERSION.tgz and SHA256SUMS from the releases page, check the file, and switch to it:

sha256sum --check --ignore-missing SHA256SUMS
sudo imbox-activate imbox-VERSION.tgz VERSION

Either way you should see:

Release VERSION is live.

If the new release does not answer a health check within about a minute, the script puts the previous one back and prints the service log. See Troubleshooting.

3. Check itCopy Anchor Link

On the server:

curl -s http://127.0.0.1:8787/healthz

You should get {"ok":true}. Then open https://imbox.example.com in a browser. It sends you to a sign-up page, where you make the owner account. Carry on with First run.

After the installCopy Anchor Link

• Run sudo bash imbox/deploy/harden.sh for key-only SSH, fail2ban and automatic security updates.
• Read Self-hosting for backups, restore and running several processes.
• Your settings live in /etc/imbox/imbox.env. See Configuration.

Docker ComposeCopy Anchor Link

This runs imbox and its database in containers. The container listens on 127.0.0.1:8787 only, so you put a reverse proxy in front of it for HTTPS.

1. Get the files and set three valuesCopy Anchor Link

git clone https://github.com/fr3on/imbox.git && cd imbox
cp .env.example .env

Open .env and set:

Compose stops with a message naming the setting if one of these is empty.

2. Start itCopy Anchor Link

docker compose up -d

The compose file pulls the published image. If your copy of the repository has no published image yet, build it yourself: in docker-compose.yml, comment out the image: line and uncomment build: ., then run docker compose up -d --build.

3. Add HTTPSCopy Anchor Link

Any reverse proxy works. With Caddy, which gets certificates on its own, the whole file is:

imbox.example.com {
	reverse_proxy 127.0.0.1:8787 {
		flush_interval -1
	}
}

The flush_interval line makes live updates reach the browser as they happen.

4. Check itCopy Anchor Link

docker compose ps
curl -s http://127.0.0.1:8787/healthz

Both containers should be running, and the second command should print {"ok":true}. Open your address and carry on with First run. If something is wrong, docker compose logs -f imbox shows why.

To update later, run docker compose pull && docker compose up -d. See Updating.

RailwayCopy Anchor Link

Railway runs it for you, with no server to look after. See the Railway guide.

Where to go nextCopy Anchor Link

1. First run: make the owner account, turn on two-factor sign-in, connect your first mailbox.
2. Troubleshooting: if the site doesn't open or something misbehaves.
3. Configuration: every setting, and what changes when you change it.