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 most use cases where you need a reliable transactional email service.

In general, on a server with 4GB RAM and 2 vCPUs, you should be able to easily send more than 1,000,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. Add more IP addresses for more queues.

OS: A Linux-based operating system. Hyvor Relay is tested on Ubuntu 24.04 LTS in production.

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

OpenID Connect (OIDC) Provider: Hyvor Relay relies on OIDC for authentication. Create an application in your OIDC provider and obtain the issuer URL, client ID, and client secret. Then, allow the following URLs:

  • Callback URL: http://your-server-ip/api/oidc/callback
  • Logout URL: http://your-server-ip

Firewall: the following ports should be open on your server:

  • 80: API
  • 25: SMTP server for incoming emails (bounces & complaints)
  • 53: DNS Server

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 following files:

.env 			 	# Environment variables
compose.yaml			# Docker Compose file
config			 	# Bash script to update .env file

2. Configure Environment Variables

Run the config script:

./config

This script does the following, in order:

  • Set APP_SECRET to a secure random value in .env file, generated using openssl rand -base64 32.
  • Generate a strong random password for the Postgres database and update the DATABASE_URL variable in .env file and the corresponding variable in compose.yaml.
  • Prompt you to enter the OIDC provider details (issuer URL, client ID, client secret) and update the corresponding variables in .env file.

Make sure to verify the config:

cat .env
cat compose.yaml

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

3. Start Docker Compose

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.

Things to know

App Secret

The APP_SECRET variable is a 32-bytes key used to encrypt sensitive data (e.g., API keys, tokens) in the application. You should not change this value after the initial setup, as it will invalidate existing encrypted data. Key rotation is not supported yet, but planned.

Host Network

The application uses the host network mode to bind to the server's IP addresses directly. This allows Hyvor Relay to control the IP addresses used for sending emails. Other network modes (e.g., bridge, overlay) are not supported.

External Postgres

If you want to use an external Postgres database (for example, a managed database service), you can do so by updating the DATABASE_URL environment variable in the .env file.