Community Open Source
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 4SENDER_EMAIL
- the from address for emails sent by your EnvKey hostDATABASE_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 to3307
EMAILS_PER_SECOND
- limits email sending rate per second (excess emails are queued and sent over time), defaults to10
EXPRESS_PORT
- the port to run the main EnvKey server on, defaults to3000
SOCKET_PORT
- the port to run the EnvKey websocket server on, defaults to3002
EMAIL_TOKEN_EXPIRATION_MS
- how long email authentication tokens are valid in milliseconds, defaults to86400000
(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 anUpgrade
header set towebsocket
. All other requests should be forwarded to port3000
(or the value of theEXPRESS_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.
Updated over 1 year ago