Easy Deploy

This page covers how to deploy Hyvor Relay on a single server using Docker Compose. This is the easiest way to deploy Hyvor Relay, and it is suitable for testing Hyvor Relay or for small to medium-sized use cases.

In general, on a server with 4GB RAM and 2 vCPUs, you should be able to easily send more than 100,000 emails per day. However, if you need high availability and scalability, see the Prod Deploy page, which uses multiple servers with Docker Swarm.

Prerequisites

Server: A server with at least 1GB RAM and 1 vCPU. 2GB RAM and 2 vCPU are recommended for production use.

IP Addresses: You need at least one static IPv4 address for the server, which will be assigned to the transactional queue.

OS: A Linux-based OS is recommended for production use. If you are not sure, use Ubuntu 24.04 LTS, the same OS our Cloud runs on.

Docker: Install the latest version, following the official guide.

OpenID Connect (OIDC) Provider: Hyvor Relay relies on OIDC for authentication.

Install

1. Download Deployment Files

First, download the latest deployment files (view on Github).

curl -LO https://github.com/hyvor/relay/releases/latest/download/deploy.tar.gz
tar -xzf deploy.tar.gz
cd deploy/easy

deploy/easy directory contains the Docker Compose files and other necessary files for this deployment.

2. Configure Environment Variables

The .env file contains the environment variables for the deployment. Open it in a text editor and set the following variables:

App Secret

The APP_SECRET variable is a 32-bytes key used to encrypt sensitive data (e.g., API keys, tokens) in the application. Use the following command to generate a base64-encoded key:

openssl rand -base64 32

OIDC Configuration

Hyvor Relay requires OIDC (OpenID Connect) for authentication. In your OIDC provider, create a new application and set the following values:

OIDC_ISSUER_URL=https://your-oidc-provider.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

You might also need to allow the following URLs in your OIDC provider:

  • Callback URL: https://your-relay-domain.com/api/oidc/callback
  • Logout URL: https://your-relay-domain.com

If needed, feel free to change other environment variables. See the Environment Variables page for all available variables.

3. Start Docker Compose

Once you have configured the environment variables, you can run the following command to start the services:

docker compose up -d

This command will start the Hyvor Relay services in detached mode. You can check the logs using:

docker compose logs -f app

You should see the logs indicating that the application has run migrations, configured the server and the IP addresses, and started the application (email workers, webhook workers, etc.).

Setup

Once the application is running, you should see the Hyvor Relay homepage at http://your-server-ip.

Next, head to the Setup page to learn how to set up your Hyvor Relay instance for best deliverability.

HYVOR © 2025
From France 🇫🇷