Overview

EnvKey Community Open Source is free and open source software under the MIT license. It can run from a single pre-compiled binary on Linux (recommended) or from source on any system compatible with Node.js.

Requirements

A Linux system (to run from pre-compiled binary) or any system compatible with Node.js (to run from source)
A MySQL 8 host with a database created for EnvKey
SMTP credentials for sending emails (SMTP server can be self-hosted or you can use a service like Sendgrid, Mailgun, or AWS SES)
A domain name you can add DNS records to and a valid TLS certificate (EnvKey clients can only make TLS requests)

Setup & Deployment

1.) Install the EnvKey UI and CLI on your local machine.

2.) Open the EnvKey UI and click Create A New Organization.

3.) On theChoose Your Host screen, select Community Open Source.

4.) Copy the value displayed for COMMUNITY_AUTH_HASH and store it temporarily for later use.

5.) To start from pre-compiled binary: on the machine where you will host EnvKey Community Open Source, download the api.community.zip file from the latest apicommunity release and unzip it.

You can verify the release with minisign.

To start from source:

clone the EnvKey github repo
install the Node.js version specified in .nvmrc
install dependencies with ./public/scripts/install_deps

6.) To start from pre-compiled binary: execute the envkey-api file.

To start from source: run ./public/scripts/start_api_community_prod

With either method, the following environment variables must be set:

COMMUNITY_AUTH_HASH - the value you copied from the UI in step 4
SENDER_EMAIL - the from address for emails sent by your EnvKey host
DATABASE_HOST - the host address of your database (example: localhost, 232.245.95.13, db.mydomain.com)
DATABASE_NAME - the name of a database created for EnvKey (example: envkey)
DATABASE_CREDENTIALS_JSON - database credentials as json in the following format: {"user": "your-db-user", "password": "your-db-password"}
SMTP_TRANSPORT_JSON - SMTP credentials as json in the format specified here under 'General options' and 'TLS options'

The following environment variables can also be set, but are optional:

DATABASE_PORT - database port, defaults to 3307
EMAILS_PER_SECOND - limits email sending rate per second (excess emails are queued and sent over time), defaults to 10
EXPRESS_PORT - the port to run the main EnvKey server on, defaults to 3000
SOCKET_PORT - the port to run the EnvKey websocket server on, defaults to 3002
EMAIL_TOKEN_EXPIRATION_MS - how long email authentication tokens are valid in milliseconds, defaults to 86400000 (24 hours)

7.) If you don't already have a domain, purchase a domain to use for your EnvKey host.

8.) Choose a subdomain to use for your EnvKey host (EnvKey requires a subdomain and cannot run from the root domain).

9.) If you don't already have a TLS certificate for your domain (that also covers the subdomain you chose in the previous step), obtain one.

10.) Expose your EnvKey server to the internet (using NGINX, a load balancer, or whatever other tools you prefer).

In order to enable websocket connections (which EnvKey relies on), add a rule to your configuration that forwards requests to port 3002 (or the value of theSOCKET_PORT environment variable in step 6 ) if they include an Upgrade header set to websocket. All other requests should be forwarded to port 3000 (or the value of the EXPRESS_PORT environment variable in step 6).
Also be sure TLS is configured correctly using the domain, subdomain, and certificate from the previous steps.

11.) Set a CNAME or A record on your domain for the subdomain you chose in step 8--set it to the endpoint of your EnvKey host from the previous step.

12.) Make a GET request to https://your-subdomain.your-domain.com and confirm you get an API OK response.

13.) Back in the EnvKey UI on your local machine, fill in the Domain and Subdomain fields and click the Next button.

14.) You're just about done. Follow the in-app instructions to finish creating a new organization.