🏠
Self-Host Guide
Last Updated: Jul 18, 2021.

➡️
This guide describes how to self-host Reacher. There are currently 3 ways: 1. One-Click Deploy to Heroku (Recommended 🏅) 2. Using Docker 3. Build the source locally on your server

Prerequisites

Before self-hosting Reacher, make sure you have the permission to self-host!
Reacher is licensed under a dual open-source OR commercial license:
  • For open-source projects compatible with the AGPL-3.0 license, simply deploy Reacher under the terms of this license.
  • If you are using Reacher commercially in a closed-source project, you might need to purchase a commercial license. See 🎓Reacher Licenses for more information.

Free Trial

If you wish to have a free trial before purchasing the commercial license, it should be safe to use the open-source AGPL-3.0 licensed code for a short period of time, internally and for non-commercial purposes.

1. One-Click Deploy to Heroku (Recommended 🏅)

This method is the easiest way to deploy Reacher. It uses Heroku, a developer-friendly Platform-as-a-Service.

Requirements

  • A Heroku account. You can create one for free.

Step-by-Step Guide

  1. Visit https://github.com/reacherhq/backend.
  1. Click on the "Deploy to Heroku" purple button.
  1. Choose an app-name for you app, and click on "Deploy App".
  1. Wait for the deployment to finish. This usually takes ~15 minutes.
  1. Once deployed, you're ready to do email verifications:
curl -X POST \
-H'Content-Type: application/json' \
-d'{"to_email":"amaury@reacher.email"}' \
https://{app-name}.herokuapp.com/v0/check_email

2. Using Docker

Requirements

  • A cloud provider which accepts deploying Docker images. You may use the platform of your choice, but make sure that the port 25 is open. To avoid spamming, most providers don't actually open port 25 automatically, see FAQ below for more details.
  • Docker.

Step-by-Step Guide

The Docker image is hosted on Docker Hub: https://hub.docker.com/r/reacherhq/backend.
Since self-hosting using Docker is really specific on which platform you use, we will only be demonstrating how to use Docker on your local machine.
  1. Run docker run -p 8080:8080 reacherhq/backend
  1. Once set up, you're ready to do email verifications
curl -X POST \
-H'Content-Type: application/json' \
-d'{"to_email":"amaury@reacher.email"}' \
http://localhost:8080/v0/check_email
Since email verifications are stateless, they are well-suited for horizontally-scaling deployments, for example using Kubernetes.

3. Build Reacher Locally on your Server

Requirements

  • Access to a server. Make sure that ports 25 (for outbound SMTP connections) and 8080 (for inbound HTTP connections) are open on your server.
  • Make sure openssl is installed too.

Step-by-Step Guide

  1. Clone the repo git clone https://github.com/reacherhq/backend.
  1. Run the binary cargo run --release
  1. Once the binary is built and running, you're ready to do email verifications:
curl -X POST \
-H'Content-Type: application/json' \
-d'{"to_email":"amaury@reacher.email"}' \
http://localhost:8080/v0/check_email
For configuring the server, please see the environment variables you can set: https://github.com/reacherhq/backend#configuration.

F.A.Q.

How do I know if port 25 is open?

Reacher performs real-time SMTP email verifications, which means that outbound connections on port 25 must be open. Most ISPs block port 25 to avoid spamming, this is why email verifications often don't work from your local machine.
As a result, Reacher recommends to run the email verification software from a cloud provider. It is essential that the chosen cloud provider has port 25 open!
Here are details about some of the most well-known providers:
  • ✅ Heroku: Reacher's own SaaS backend is currently on Heroku. However, please note that according to this document, port 25 can intermittently have difficulty sending requests.
  • ⚠️ AWS: Needs an application to open port 25, link to apply.
  • ⚠️ Digital Ocean: Your account needs to be 60d old, then you can apply to open port 25.
  • ❌ GCP: Port 25 closed, source.
Another solution is to host Reacher on a cloud provider, and use a proxy (which has port 25 open) before hitting the recipient SMTP server. Reacher does NOT provide any consultation, service or advice on proxies. Please make your own research.

What about IP blacklisting?

Each email verification creates a new SMTP connection to the recipient's email provider. This means that under high volume, said email provider can decide to blacklist your IP address. One way to bypass blacklisting is to implement an IP rotation proxy before hitting the email provider.
Reacher does NOT provide any consultation, service or advice on IP rotation. Please make your own research.

How can I debug "is_reachable": "unknown"?

Reacher's backend comes with an optional support of bug tracking using Sentry. You can create an account for free, and set the RCH_SENTRY_DSN environment variable on your server. Every time your server receives an email with "is_reachable": "unknown", anonymized logs will be sent to Sentry. Below is an example screenshot of Reacher's own Sentry dashboard:
notion image
Clicking on each Sentry ticket will also show the exact error message with some context, which should give you indications on why the result was "unknown"(IP blacklisting, timeouts...). Feel free to contact ✉️ amaury@reacher.email if you need help debugging these errors.

Any other questions?

Please contact ✉️ amaury@reacher.email.