Octeth v6.0.7 Now Available! See What's New

Stage 4 of 12

Install Octeth for Your Email Service Provider

Install Octeth on the app server, set up TLS for the app domain, make the app's own emails reach the inbox, create the admin and staff accounts, and brand everything your customers and their recipients see. This guide covers the decisions and the order. Octeth's docs hold the commands for your version.

By Cem Hurturk, founder of Octeth Updated 12 min read

Skills
  • Octeth installer
  • TLS certificates
  • SMTP for system mail
On this page
  1. Pick the app domain and get the license
  2. Choose how you run the installer
  3. TLS for the app domain
  4. System mail
  5. The main administrator and staff accounts
  6. Brand the install
  7. Google sign-in
  8. Before you open signups

Install Octeth after the servers are ready, and before you build plans or open signups. The order matters. Pick the app domain and license first, install with the firewall already in place, set up TLS, then make the app’s own email work before any customer can sign up. Branding comes last, because you check it on a working install.

This guide assumes the app server from server infrastructure: Ubuntu 24.04 LTS, hardened, Docker from Docker’s repository, the firewall script applied and the app domain proxied by Cloudflare. If you install Octeth to send for one business only, Octeth’s installation docs are all you need. This guide adds what changes when many customers use the install.

Pick the app domain and get the license

The app domain is the address your customers type to log in, such as app.example.com. Decide it before anything else, for two reasons:

  • The license is tied to it. The license key comes from my.octeth.com and is signed for one host. A key for another host is refused, and so is a short key from an older version. A fresh install has no grace period: without a valid key it runs with Community limits.
  • The customer interface works only on that host. Octeth builds every link in the new interface from the app URL, and serves its origin certificate only for that host. API and admin paths answer on any hostname that reaches the server, but your customers’ interface does not.

Use your own brand’s domain, not a hostname that names your provider or Octeth. Keep your sending infrastructure on a separate domain. Stage 3 explains why.

Octeth’s installer lets you leave the key blank and paste it later on the License section of the staff System screen (from 6.0.2). Until then the install runs with Community limits. For an ESP, install with the real key, so you never test against limits your customers will not have.

Choose how you run the installer

Octeth ships as a release zip with a CLI installer. It checks the server, asks for the app URL, the main administrator and the license, then starts the containers. The install takes several minutes. Pick one of three ways to run it:

WayWhen it fits
Interactive promptsOne install, done by hand, by someone watching the screen
Unattended, with flags and secret filesRepeatable installs from a script or a runbook. This is how we install.
An AI coding agent following Octeth’s agent instructionsYou want the agent to handle the steps and stop for DNS, port 25 and sizing decisions

The CLI tool reference lists the unattended flags. The installation page covers the agent path.

Whichever way you choose, protect the secrets:

  • Pass the admin password and license key from files readable only by root, not as command-line flags. Recent versions accept both from files. Delete the files after the install.
  • Keep the install log private. On 6.0.0 it contains generated secrets, such as the code the tracking edge uses to ask Octeth which domains it may serve. If that log is ever exposed, regenerate the secret. From 6.0.1 the installer no longer prints them.
  • Run the installer with the default umask. A strict umask makes the installer write settings files the app cannot read.
  • On a server with fewer than 4 cores, check the send engine and link proxy CPU limits before the install. Stage 3 explains why.

Check the install before you go on

The health check fails until TLS is in place, so set up TLS first, then check:

  1. Every container reports healthy, and Octeth’s health check returns every check OK. Run it a minute after any container restart.
  2. The new interface answers on the app domain through Cloudflare.
  3. From an IP outside your admin list, every port your firewall closes still times out.

TLS for the app domain

How you set up TLS depends on how the app domain resolves. Octeth’s SSL certificates page has the steps for each path.

PathHow TLS worksFits
App domain points straight at the serverOcteth’s Caddy gets a certificate from Let’s Encrypt on the first request, and renews it. If the first HTTPS request ends in a TLS error, recreate the link proxy container once (docker compose up -d --force-recreate link_proxy, from the Octeth install directory) and retry.Installs with no proxy in front. Ports 80 and 443 must be open to everyone.
Cloudflare in front, Origin CA certificateYou place a Cloudflare Origin CA certificate on the server, and Octeth’s HAProxy terminates TLS with itAn ESP behind Cloudflare. This is the setup we recommend.

For an ESP behind Cloudflare, use the Origin CA certificate. Stage 3 locks the origin to Cloudflare and your admin IPs, and this path fits that setup. It also lets Octeth record each visitor’s real IP once its trusted proxies list Cloudflare’s ranges. Login throttling and audit logs depend on the real IP. Do not plan on letting Caddy issue the certificate while Cloudflare proxies the app domain.

Two things to know about the Origin CA path:

  • Only Cloudflare trusts the certificate. If you pause Cloudflare or turn off proxying for the app domain, visitors get certificate errors. Calls from the server to its own app domain must also go through Cloudflare. Stage 3 covers the hosts file entry that breaks this.
  • Cloudflare does not warn you before it expires. Put the expiry date in your monitoring or your calendar.

Never use Cloudflare’s Flexible mode for the app domain. It sends traffic between Cloudflare and the server unencrypted, API keys included.

Tracking hosts and the SMTP host are separate. Customers’ tracking hosts get certificates on demand from the tracking edge in stage 3. The SMTP relay needs its own certificate before customers use port 587.

System mail

Octeth sends its own emails: signup verification, password resets, account notices and alerts to your staff. This is system mail. It is separate from your customers’ campaigns, which go out through delivery servers and your MTA.

Two senders to configure

Octeth has two places that send system mail, and both need a real mail server:

  • The new interface sends signup verification, password resets and its other account emails. Its mailer setting starts as log, which writes each message to a log and never delivers it. Point it at an SMTP server with the UI_MAIL_* settings in the configuration reference.
  • The classic app sends system notices and alerts. Its send method, sender address and reply-to address are separate settings. From 6.0.2 the sender settings are on the staff Your profile screen, described in Octeth configuration, and the send method is on the staff Email delivery screen.

The new interface’s system mail is required for an ESP, not optional. A new form signup stays disabled until its owner clicks the emailed link. Recent versions hide the signup link until the interface can send mail, so a broken mailer closes signup.

Where to send it from

Send system mail through an SMTP host on a different IP from your customers’ delivery servers, from a shared support address on your main domain. Point both senders at the same host and address.

Set up the sender address before you test:

  • Use a shared address you monitor, such as hello@ or support@, for the From and Reply-To. A common mistake is a person’s mailbox as the classic system sender, which then has to be moved when that person leaves.
  • Authenticate the sender domain. It needs SPF and DKIM, and DMARC should pass. Stage 6 covers the records.

Pick a mail server for system mail that offers STARTTLS on the submission port, so passwords and message content are encrypted on the way.

Then test with real mail. Request a password reset from the sign-in page, and check that it arrives in an inbox, not spam, from your brand name. Open the message source in the mailbox and confirm that SPF, DKIM and DMARC pass.

The main administrator and staff accounts

The main administrator

The installer creates the main administrator from the name, email address, username and password you give it. This account has full control of the install.

  • Use an address you monitor. A fresh install also uses it as the complaints address in every outgoing message’s headers, until you change that setting. Octeth’s white-label checklist explains it.
  • Turn on two-factor authentication on Your profile, and store the recovery key in a password manager.
  • Treat the admin API key like a password. It has full admin access.

Staff accounts

Give every other person on your team their own sub-admin account. Each one gets only the permissions it needs and can be limited to some user groups. Keep the settings, security, sub-admin and delivery server permissions for the people who run the platform. Managing sub-admins has the screens.

Plan what staff do from day one. New signups start untrusted, so staff review each new account and mark it trusted before it can send. Stage 8 covers account review.

Where staff sign in

Staff work in the staff area under /user/staff. The classic admin also answers on /admin/ and /app/admin/. In stage 3, a Cloudflare WAF rule limits all of these paths to your admin IPs. We leave Octeth’s own admin IP allow-list empty and let the WAF rule do that job. If you use the allow-list, confirm first that Octeth records real visitor IPs, or the list blocks you.

Brand the install

What you set

The new interface is built to be white-labeled. Its brand settings cover:

  • the product name and legal name
  • a logo mark for the sidebar, a horizontal logo for signed-out pages, and the browser tab icon
  • the accent colours
  • support, terms, privacy, acceptable use and status links
  • the sender name and footer of the interface’s own emails
  • which sections customers see

Set them as UI_BRAND_* settings in Octeth’s configuration file, or on the staff Branding screen from 6.0.2. Branding the new user interface lists every setting. The classic app has its own product name setting, on the same Branding screen. It appears in the classic admin, in two-factor authenticator entries and in system email subjects, so set it as well.

What to set:

  • Name and legal name, and an email footer that names the legal entity.
  • Logos. The logo mark shows at about 30 pixels on a dark sidebar, beside the name as text. The horizontal logo shows at about 32 pixels on the white signed-out pages. Trim the empty space around both. A detailed icon turns muddy as a 16-pixel favicon, so use a simple one.
  • Colours. The stock primary colour works for most brands. Take the accent from the wordmark, with darker and lighter shades for hover and backgrounds.
  • Links. Terms and privacy on the marketing site, the acceptable use policy, and a support email address. Leave the status link empty if you have no status page, so it does not show.

Take these values from the brand owner’s guidelines and source files, not from their public website. The guidelines hold rules the site does not show, such as how the name is spelled, which logo goes where, and whether the platform behind the product may be named.

When a value contains a space or #, put it in one pair of double quotes. Branding copied from an install on an older version can carry nested quotes, which now show up as part of the text.

Check it before you open signups

Open the sign-in page, the sign-up page, the dashboard, a campaign report and one of the interface’s emails in a private window. None may name Octeth. Check the tab icon and both logos at their real sizes.

Plan your plan names and help docs around Octeth’s on-screen labels. The path settings rename a section’s address, not the label on screen, and section switches apply to every customer at once. To give one plan a feature and another plan none, use user group permissions, covered in stage 7.

What recipients see

Branding the interface changes what your customers see. It does not change what their recipients see. Message headers, the complaints address, the abuse report link, tracked link parameters and the envelope sender each carry part of your platform’s identity, and each is set separately. Work through Octeth’s white-label deployment checklist before the first campaign. Without a tracking domain, the abuse report header in every campaign shows your app’s hostname.

For what the white-label features cover across the product, see white-label email marketing software.

Google sign-in

Recent versions of Octeth can add a Continue with Google button to the sign-in and sign-up pages. It is off by default. Google sign-in has the setup.

How it behaves on an ESP:

  • Only addresses Google controls can use it: Gmail addresses, and Google Workspace accounts on their own domain. Other customers sign in with a password.
  • An existing customer signs in without the password, but two-factor authentication, IP restrictions and the login limiter still apply.
  • A new address creates an account only when self-signup is on. It gets the same signup trust level as any other signup, so with signups untrusted a Google signup still waits for review.
  • Keep Google signups untrusted until review. A Google signup is active at once, with no verification email, so review is the only check before it sends.

Setting up the Google side:

  • Create one OAuth client for each brand. The consent screen shows that client’s app domain, or its app name and logo once Google has verified the brand, so a shared client shows the wrong brand.
  • Add the redirect address exactly as your app URL followed by /user/auth/google/callback.
  • Publish the app to production with the openid, email and profile scopes. Google treats them as non-sensitive.
  • Leave the logo off the consent screen. Without brand verification the consent screen shows your app domain, not the name and logo. We skipped the logo and the review.

After you turn it on, check that the sign-in page shows the button and that the redirect reaches Google’s sign-in page without an error. Then sign in once with a real Google account and check that Octeth recorded the sign-in method and your real IP.

Before you open signups

The install is ready for the next stages, not for customers. Keep self-signup closed until system mail works, your acceptable use policy from stage 2 is linked, and staff know how to review new accounts. A fresh install has one delivery server, a local test mail catcher that no user group uses. Stage 5 adds your MTA as a delivery server and assigns it to your user groups. Until then, do not let customers send.

Before you move on

  • The app domain is the one your customers will use, and your license is issued for that exact host.
  • Stage 3 is done on the app server, including the firewall, before the install starts.
  • The installer read the admin password and license key from protected files, which 6.0.1 and later accept.
  • The health check reports every check OK, and the app answers through Cloudflare with your origin certificate.
  • You know when your origin certificate expires, and something reminds you before it does.
  • A password reset from the sign-in page arrived in a real inbox, from your brand's address.
  • The classic admin's system emails come from a shared address you monitor, not a person's mailbox.
  • The main administrator uses two-factor authentication, and every other staff member has their own limited account.
  • The sign-in page, the sign-up page, the dashboard and one of the app's emails show your brand and never name Octeth.
  • You worked through Octeth's white-label deployment checklist for what recipients see.
  • Self-signup stays closed until mail works and you have decided who reviews new accounts.

We build ESPs

Rather have us build this?

We install and configure Octeth with the Unlimited license in your name, on your domain and with your brand.

Running it yourself?

Get the Octeth license

Pick the license tier that fits your customer count.