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.
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:
http://your-server-ip/api/oidc/callbackhttp://your-server-ipFirewall: the following ports should be open on your server:
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/easydeploy/easy directory contains the following files:
.env # Environment variables
compose.yaml # Docker Compose fileEdit the .env file to set the following variables:
APP_SECRET: A strong random string. You can generate one using the following
command: openssl rand -base64 32POSTGRES_PASSWORD: Use a strong, URL-safe password for the Postgres database.
You can generate one using the following command: openssl rand -base64 32 | tr '+/' '-_' | tr -d '='WEB_URL: The public URL where Hyvor Relay and its API will be accessible.
Example: https://relay.yourdomain.com. This is required for TLS. If you run Hyvor Relay
behind a reverse proxy that handles TLS, use http://.INSTANCE_DOMAIN: The dedicated domain name used for the incoming mail server,
EHLO identification, and PTR records. Example: mail.relay.yourdomain.com. Must be different from the Web URL. DNS of this (sub)domain will be handled
by Hyvor Relay.OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET:
Set these variables based on your OIDC provider configuration.See the Environment Variables page for all available variables.
Start the services:
docker compose up -dThis command will start the Hyvor Relay services in detached mode. You can check the logs using:
docker compose logs -f relayYou 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.).
You can run the following command for a quick status check:
docker compose exec relay bin/console verifyNext, head to the Setup page to continue the setup process.
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.
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.
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.