> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install OxiMail on a fresh Debian 13 host: requirements, ports, building the binary, and running it under systemd.

OxiMail is a single Rust binary. Installing it means getting one executable onto a server, placing a config file next to it, and running it as a service. There is no Postfix, no Dovecot, and no web server to install alongside it.

This page covers getting OxiMail onto a host. Once it is running, the [first boot and setup wizard](/first-boot) walks you through DNS, DKIM, TLS, and your first account.

## Requirements

| Requirement      | Value                                                   |
| ---------------- | ------------------------------------------------------- |
| Operating system | Debian 13 (Trixie)                                      |
| Privileges       | root access                                             |
| RAM              | 2 GB minimum (compiling from source needs the headroom) |
| Disk             | 10 GB or more free                                      |
| Network          | a domain name and a public IP                           |

OxiMail is built and tested on Debian 13. The installer refuses to run on other distributions or Debian versions, because the build dependencies and library versions are pinned to that target.

<Warning>
  OxiMail **cannot be built on Windows or macOS**. The build needs OpenSSL and SQLCipher development libraries that are provided by the Debian packages below. Build on a Debian 13 machine (a VPS, an LXC container, or a VM).
</Warning>

### System dependencies

The build needs a C toolchain plus the OpenSSL and SQLCipher development headers:

```bash theme={null}
apt install -y build-essential pkg-config libssl-dev libsqlcipher-dev clang curl git
```

You also need a stable Rust toolchain. If `rustc` is not already present, install it with rustup:

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
source "$HOME/.cargo/env"
```

## Ports

OxiMail listens on the standard mail and web ports. Open them in your firewall (and any cloud provider security group) before you start the server. The setup wizard checks these and warns you about anything blocked.

| Port | Protocol | Purpose                                       |
| ---- | -------- | --------------------------------------------- |
| 25   | TCP      | SMTP inbound (receiving mail)                 |
| 80   | TCP      | HTTP, used for ACME certificate challenges    |
| 443  | TCP      | HTTPS, serving JMAP and the admin API         |
| 587  | TCP      | SMTP submission (sending mail, authenticated) |
| 465  | TCP      | SMTPS (implicit-TLS submission)               |
| 993  | TCP      | IMAPS (legacy mail clients)                   |
| 143  | TCP      | IMAP with STARTTLS (optional)                 |

Ports 25, 443, and 587 are the minimum for a working mail server. The IMAP ports (143/993) only matter if you enable the `legacy` feature for IMAP clients. CalDAV and CardDAV are served over the same HTTPS port (443) as JMAP, so they need no extra ports.

## Getting the binary

There is no published prebuilt-binary download today: you build OxiMail from source. The build produces a single self-contained executable (around 70 MB) that you copy to the server.

<Note>
  A public source repository and a one-line installer are part of the project roadmap, not something you can rely on yet. Build from source as described below. If you see a one-liner referenced elsewhere, treat it as not-yet-live and verify before depending on it.
</Note>

### Build from source

From a clone of the source tree on a Debian 13 host:

```bash theme={null}
cargo build --release --features passkey,legacy
```

The two feature flags are:

| Flag      | Effect                                       | Default |
| --------- | -------------------------------------------- | ------- |
| `passkey` | WebAuthn / FIDO2 passwordless authentication | on      |
| `legacy`  | IMAP, CalDAV, and CardDAV protocol support   | off     |

Build with `--features passkey,legacy` if you want legacy mail clients (IMAP) and DAV clients to connect. The release build takes roughly 5 to 15 minutes depending on the machine, and the binary lands at `target/release/oximail`.

A clone also ships an `install.sh` at the repository root that runs the whole sequence (system packages, Rust, compile, install, then launch the setup wizard) in one go. It is convenient on a fresh VPS, but the manual steps below give you control over each stage.

## Placing and running the binary

### Install the binary and its directories

Copy the compiled binary into place and create the runtime directories. A dedicated system user keeps the service from running as root:

```bash theme={null}
# system user (no login shell)
useradd --system --shell /sbin/nologin --home-dir /var/lib/oximail oximail

# runtime directories
mkdir -p /etc/oximail/dkim
mkdir -p /var/lib/oximail/blobs
mkdir -p /var/lib/oximail/search
chown -R oximail:oximail /var/lib/oximail /etc/oximail
chmod 700 /etc/oximail/dkim

# the binary
cp target/release/oximail /usr/local/bin/oximail
chmod 755 /usr/local/bin/oximail
```

Because OxiMail binds to privileged ports (25, 443, 587) but runs as a non-root user, grant the binary the capability to bind low ports instead of running it as root:

```bash theme={null}
setcap 'cap_net_bind_service=+ep' /usr/local/bin/oximail
```

If `setcap` is missing, install `libcap2-bin` first.

### Configuration file

OxiMail reads a single TOML config file. The conventional location is `/etc/oximail/oximail.toml`. The source tree ships a fully commented example at `config/oximail.example.toml` that you can copy as a starting point:

```bash theme={null}
cp config/oximail.example.toml /etc/oximail/oximail.toml
chown oximail:oximail /etc/oximail/oximail.toml
chmod 600 /etc/oximail/oximail.toml
```

A minimal production config sets the hostname, the bind addresses, the storage paths, and ACME for TLS:

```toml theme={null}
[server]
hostname = "mail.example.com"
bind = "0.0.0.0:443"

[storage]
sqlite_path = "/var/lib/oximail/data.db"
blob_path = "/var/lib/oximail/blobs"

[smtp]
hostname = "mail.example.com"
bind = "0.0.0.0:25"

[tls]
acme_enabled = true
acme_email = "admin@example.com"
```

The full reference, including every key and the TOML-plus-database override model, is in [Configuration](/operator/configuration). In most cases you let the [setup wizard](/first-boot) generate the config rather than writing it by hand.

### Run as a systemd service

Install a systemd unit so OxiMail starts at boot and restarts on failure. Logs go to the journal (run `journalctl -u oximail`), so there is no log file to rotate.

Create `/etc/systemd/system/oximail.service`:

```ini theme={null}
[Unit]
Description=OxiMail JMAP Mail Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/oximail serve --config /etc/oximail/oximail.toml
Restart=on-failure
RestartSec=5
LimitNOFILE=65535
WorkingDirectory=/var/lib/oximail
StandardOutput=journal
StandardError=journal
SyslogIdentifier=oximail

[Install]
WantedBy=multi-user.target
```

Then enable and start it:

```bash theme={null}
systemctl daemon-reload
systemctl enable --now oximail
journalctl -u oximail -f
```

For interactive setup the first time, you can run `oximail setup` directly instead of starting the service. The wizard creates the config, your admin account, and your DKIM keys, then hands off to the service.

## What's next

* [First boot and setup wizard](/first-boot) — configure DNS, DKIM, TLS, and create your first account.
* [Configuration](/operator/configuration) — the full TOML reference and the runtime override model.