Installation

Kurrier can be self-hosted on any modern Linux, macOS, or ARM device (including Raspberry Pi). It’s distributed as a Docker setup for convenience, but you can also run it manually from source if you prefer.

🧱 Kurrier’s core stack: Next.js + Nitro (API worker) + Postgres + Redis + IMAP/SMTP connectors

Prerequisites

Before you start, make sure you have:

• Docker and Docker Compose installed → Install Docker
• Git (for cloning the repository)
• At least 1 GB RAM and 1 vCPU (2 GB+ recommended for production)
• Optional: a domain name (for mail.yourdomain.com or similar)

Quick start (Docker)

Clone the repository and copy the example environment file:

git clone git@github.com:kurrier-org/kurrier.git
cd kurrier/db
cp example.env .env
cp -r ./init/volumes/ volumes

Open the .env file and update your secrets and passwords. You can also use the built-in secrets generator below to create a secure, production-ready passwords and secrets.

REDIS_PASSWORD=replace_with_your_redis_password
RLS_CLIENT_PASSWORD=replace_with_your_rls_client_password
TYPESENSE_API_KEY=supersecretkey
POSTGRES_PASSWORD=your-super-secret-and-long-postgres-password
JWT_SECRET=your-super-secret-jwt-token-with-at-least-32-characters-long
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJhbm9uIiwKICAgICJpc3MiOiAic3VwYWJhc2UtZGVtbyIsCiAgICAiaWF0IjogMTY0MTc2OTIwMCwKICAgICJleHAiOiAxNzk5NTM1NjAwCn0.dc_X5iR_VP_qT0zsiyj_I_OZ2T9FtRU2BBNWN8Bu4GE
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyAgCiAgICAicm9sZSI6ICJzZXJ2aWNlX3JvbGUiLAogICAgImlzcyI6ICJzdXBhYmFzZS1kZW1vIiwKICAgICJpYXQiOiAxNjQxNzY5MjAwLAogICAgImV4cCI6IDE3OTk1MzU2MDAKfQ.DaYlNEoUrrEn2Ig7tqibS-PHK5vgusbcbo7X36XVt4Q
DASHBOARD_USERNAME=supabase
DASHBOARD_PASSWORD=this_password_is_insecure_and_should_be_updated
SECRET_KEY_BASE=UpNVntn3cDxHJpq99YMc1T1AQgQpc8kfYTuRgBiYa15BLrx8etQoXz3gZv1/u2oq
VAULT_ENC_KEY=your-encryption-key-32-chars-min

🔐 Generate Secrets Automatically

If you don’t want to manually craft all the passwords and JWT keys, you can generate them instantly using the built-in generator below. It creates a secure, production-ready .env block with everything filled in — including the compatible JWT keys.

🧩 Local vs. Hosted Setup

Kurrier can run in two modes — local and hosted (on a VPS etc with a domain name). Both work the same way, but differ in how external services like AWS SES, SendGrid, or Mailgun can reach your server.

🖥️ Local Setup

If you’re running Kurrier on your own laptop or private machine (http://localhost or internal IP), email providers can’t reach your API directly to deliver incoming messages or webhooks.

To solve this, Kurrier allows you to define your own public tunnel URL via any tunneling service such as ngrok, Cloudflare Tunnel, or LocalTunnel.

Example using ngrok:

  ngrok http 3001

You can also use any other tunneling service of your choice.

Update your .env file with the generated public URL:

LOCAL_TUNNEL_URL=https://your-ngrok-tunnel-url.ngrok-free.app

🖥️ Hosted Setup

When hosting Kurrier on a server or cloud instance (e.g. DigitalOcean, AWS, Hetzner, or your own VPS), you should use your own domain and disable tunneling by removing or commenting out the LOCAL_TUNNEL_URL variable in your .env file.

WEB_URL=https://www.yourdomain.com // just an example

✅ Once you are all set with your environment variables you are now ready to run

docker compose up -d

✅ To stop Kurrier, run

docker compose down

🧭 Access the Dashboards

Once Docker finishes starting up, open the following URLs in your browser: