Installation Quickstart

Follow this walkthrough to install and configure a simple instance of Emissary on your local machine. Visit the configuration for more complete instructions.

Prerequisites

Go compiler - Download and install the Go compiler. You’ll need version 1.19 or higher to compile and run Emissary.

MongoDB database - Access to a mongodb database. You can download and install this locally, or sign up of a number of services that will host one for you, such as MongoDB Atlas, Digital Ocean, A2 Hosting, or Kamatera.

SMTP Server - Emissary sends a small number of transactional emails for things like user welcome messages. For test purposes, it’s fine to use your own email account, or to use a test email service like MailTrap

Emissary Source Code - Check out the source code via Git, or download a .ZIP archive directly from GitHub.

Install and Configure

In your terminal, navigate to the directory where you extracted the Emissary source code, then enter this command to start the configuration console:

> go run server.go --setup

The setup console should open in your desktop browser. If it does not, just open a browser and navigate to http://localhost:8080 to begin. By default, this will create and edit a file called config.json in the current folder. There are many other startup and configuration settings that we will skip over for this quickstart. Later, you can dig into more details in the the Configuration section.

Choose “Domains” in the top navigation bar. This is where we’ll set up your test instance. Click “Add a Domain” and then fill in the pop-up with your test domain info:

Label: My Test Domain
Hostname: localhost
MongoDB Connection String: <connection string for your mongodb database>
MongoDB Database Name: <name of a new, empty database to populate> 

SMTP Setup: SMTP information to send your welcome email
Account Owner: Your name, site username, and email

Click “Save Changes” to create your new website and send yourself a simple welcome email with a link to set up your password. If you don’t receive the email, you can always adjust your SMTP settings and resend the message by clicking the “Users” button. But don’t click the link just yet, because your Emissary domain isn’t live yet, so the link will not work.

In a production system, you might customize many other settings such as the kind of Templates available to domains, or the external services that they can connect to. A large hosting provider might also set up many, many domains to run in a clustered or load balanced environment. But this is all we need to do for our quickstart, so we’ll leave all the rest for later.

IMPORTANT The setup server IS NOT PASSWORD PROTECTED, and you should never run it on a publicly available server.

Run Emissary

Open a new terminal on your computer, navigate to the location of the Emissary source code, and enter the following command to run Emissary in live mode: > go run server.go

Your website should be running now. If you haven’t checked yet, check your email for your welcome message. If you haven’t received it, go back to the setup console and verify that it was sent correctly.

Once you receive your welcome email, click the link to open up your test website at http://localhost. Enter your new password and then you’ll see the setup wizard, which guides new site owners through the rest of the setup process.

More Templates

Emissary comes with a few other simple templates for you to use. You can create and publish your own templates using a composable set of actions, state machines, HTML templates, and data schemas. More about Templates