Nango Docs home pagelight logo
Self-Host Nango
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.

Your can customize the callback URL by adding a 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>
The Frontend SDK does not need the Secret key to initiate OAuth flows.

​
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).