Self-Hosting Instructions
Nango is recent and moving fast. As a result, you should expect occasional breaking changes. While we will do our best to assist you, we recommend that you use Nango Cloud if you do not want to deal with migrations.
​Server URL, Callback URL & Custom Domains
Add server environment variables for the instance URL and port (in the .env
file or directly on Heroku/Render):
NANGO_SERVER_URL=<INSTANCE-URL>
SERVER_PORT=<PORT>
The resulting callback URL for OAuth will be <INSTANCE-URL>/oauth/callback
.
NANGO_CALLBACK_URL
environment variable (in the .env
file or directly on Heroku/Render).If your are using a custom domain, you should change the NANGO_SERVER_URL
server environment variable accordingly (in the .env
file or directly on
Heroku/Render).
​Persistent storage
If deploying with Docker Compose (e.g. AWS, GCP, DO), the database is bundled in a docker container with transient storage. This means that updating the Docker image causes configs/credentials loss. This is a no-go for production.
Connect Nango to an external Postgres DB that lives outside the docker setup to mitigate this.
To do so, modify the default values of the following server env variables (in
the .env
file):
NANGO_DB_USER=<REPLACE>
NANGO_DB_PASSWORD=<REPLACE>
NANGO_DB_HOST=<REPLACE>
NANGO_DB_PORT=<REPLACE>
NANGO_DB_NAME=<REPLACE>
NANGO_DB_SSL=true
Deploying with Render or Heroku automatically generates a persistent database connected to your Nango instance.
For Render, the environment variables above are automatically set for you. For Heroku, check out our Heroku docs page for specific instructions.
​Securing your instance
​Securing the API
You can secure your instance’s API by adding the NANGO_SECRET_KEY
env variable
(in the .env
file or directly on Heroku/Render).
This will require Basic Auth for all sensitive API requests, e.g.:
curl '<INSTANCE-URL>/connection/<CONNECTION-ID>?provider_config_key=<CONFIG-KEY>' -u '<SECRET-KEY>:'
Notice the :
character appended after <SECRET-KEY>
.
If you are using the Node SDK, when initializing the Nango
object, pass in the
Secret key in the secretKey
parameter.
import { Nango } from '@nangohq/node';
let nango = new Nango({
host: 'http://localhost:3003',
secretKey: '<SECRET-KEY>'
});
You should also configure the CLI to authenticate with Nango. Add to your
.bashrc
(or equivalent):
export NANGO_SECRET_KEY=<SECRET-KEY>
​Securing the dashboard
By default, the dashboard of your Nango instance is open to anybody who has access to your instance URL.
You can secure it with Basic Auth by setting the following environment variables and restarting the server:
NANGO_DASHBOARD_USERNAME=<PICK-A-USERNAME>
NANGO_DASHBOARD_PASSWORD=<PICK-A-PASSWORD>
​Encrypt sensitive data
You can enforce encryption of sensitive data (tokens, secret key, app secret) using the AES-GCM encryption algorithm. To do so, set the following environment variable to a randomly generated 256-bit base64-encoded key:
NANGO_ENCRYPTION_KEY=<ADD-BASE64-256BIT-KEY>
Once you restart the Nango server, the encryption of the database will happen automatically. Please note that, at the current time, you cannot modify this encryption key once you have set it.
​Telemetry
We use telemetry to understand Nango’s usage at a high-level and improve it over time.
Telemetry on self-hosted instances is very light by default. We only track core actions and do not track sensitive information.
You can disable telemetry by setting the env var TELEMETRY=false
(in the
.env
file or directly on Heroku/Render).