Step-by-step guide to deploy Nango on AWS ECS (Fargate)
Nango can be deployed on an AWS ECS cluster using AWS Fargate. Below are the detailed steps, based on common configuration practices, to get a Nango stack up and running. Before proceeding, it’s helpful to understand the core components of a Nango self-hosted deployment, which are detailed in the Nango Infrastructure Components documentation.
We will first set up the necessary AWS infrastructure, including a VPC, security groups, RDS PostgreSQL database, Elasticache and S3 bucket.
Then, we will configure an ECS cluster using AWS Fargate, define the necessary task definitions for Nango’s microservices, and create the corresponding ECS services.
Finally, we’ll set up a load balancer to expose the Nango server.
Remember to replace placeholder values with your actual configuration and adjust resource sizes based on your expected load. For further assistance, reach out to the Nango customer support.
A Virtual Private Cloud (VPC) is recommended to host the resources.
10.0.0.0/16
).0.0.0.0/0
). Egress should allow traffic to the ECS service security group.Store the Nango secrets securely.
nango/nango-encryption-key
).nango/elasticache-auth-token
).Nango requires a PostgreSQL database.
If you already have a PostgreSQL database (version 16.1 or higher recommended) that you want to use, you can skip the creation steps below.
postgresql://<user>:<password>@<host>:<port>/<database_name>
.aurora-postgresql
. Use a compatible version (>= 16.1).nango
.postgres
(or choose another).large
instance type is recommended).No
.Nango requires a Redis-compatible cache like Elasticache.
nango-cache-private-sng
.nango-valkey
.8.0
).6379
(default).cache.t3.small
).nango-cache-private-sng
created above.NANGO_REDIS_URL
env var.Nango may require an S3 bucket for storing integration-related data.
nango-integrations
).AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
securely.GetObject
, PutObject
, DeleteObject
, ListBucket
) limited to this specific bucket. These keys will be needed as environment variables for Nango services.nango-cluster
).An Application Load Balancer (ALB) is used to expose the Nango server service.
nango-server-tg-80
./health
nango-server-tg-3009
./
nango-alb
.Define the container configurations for each Nango service using Fargate.
Go to AWS ECS > Task Definitions.
Create New Task Definition:
awsvpc
.ecsTaskExecutionRole
or ensure one exists with permissions to pull images and write logs. It also needs permission to access the Secrets Manager secret for the encryption key.Define Containers: Create one task definition for each Nango service (Server, Jobs, Persist, Orchestrator, Runner), configuring the container settings within each:
Common Settings for all Containers:
nangohq/nango:<TAG>
(use a specific, stable tag, e.g., nangohq/nango:cbacc6a4fd4306a4245d774204a2b837e6f39599
).NANGO_ENTERPRISE
: true
NODE_ENV
: production
NODE_OPTIONS
: --max-old-space-size=N
, replace with value equals to 3/4 of task memoryNANGO_DATABASE_URL
: The database connection URL from RDS (use dynamic reference or Secrets Manager). Format: postgresql://<user>:<password>@<host>:<port>/<db_name>
.NANGO_ENCRYPTION_KEY
: Reference the value from the AWS Secrets Manager secret created earlier.NANGO_REDIS_URL
: Reference the Elasticache primary endpoint created earlier.NANGO_LOGS_ENABLED
: true
(Set to 'false'
to disable Nango logs).NANGO_LOGS_ES_URL
: Elasticsearch endpoint URL, required if NANGO_LOGS_ENABLED=true
. ex:https://my.elastic.cluster:9500
.NANGO_LOGS_ES_USER
: Your Elasticsearch username.NANGO_LOGS_ES_PWD
: Your Elasticsearch password.awslogs
driver pointing to a CloudWatch log group (e.g., ecs/nango
).Nango Server Container:
server
.["packages/server/entrypoint.sh"]
.SERVER_PORT
: 80
FLAG_SERVE_CONNECT_UI
: true
NANGO_SERVER_URL
: The public URL of the ALB (e.g., http://ALB.DNS
).NANGO_PUBLIC_SERVER_URL
: Same as NANGO_SERVER_URL
.NANGO_PUBLIC_CONNECT_URL
: The public URL of the ALB with port 3009 (e.g., http://ALB.DNS:3009
).SMTP_URL
: The url of your SMTP server (ex: smtps://username:password@my-stmp-server.com:465
)SMTP_FROM
: The email address used to send emailsAWS_BUCKET_NAME
: Name of the S3 bucket.AWS_ACCESS_KEY_ID
: Access key for S3 bucket user.AWS_SECRET_ACCESS_KEY
: Secret key for S3 bucket user.AWS_REGION
: AWS region for the S3 bucket.ORCHESTRATOR_SERVICE_URL
: http://orchestrator.nango.internal:3008
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Jobs Container:
jobs
.["node", "packages/jobs/dist/app.js"]
.ORCHESTRATOR_SERVICE_URL
: http://orchestrator.nango.internal:3008
.PERSIST_SERVICE_URL
: http://persist.nango.internal:3007
.RUNNER_TYPE
: REMOTE
RUNNER_SERVICE_URL
: http://runner.nango.internal:3006
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Persist Container:
persist
.["node", "packages/persist/dist/app.js"]
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Orchestrator Container:
orchestrator
.["node", "packages/orchestrator/dist/app.js"]
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Runner Container:
runner
.["node", "packages/runner/dist/app.js"]
.RUNNER_NODE_ID
: 1
PERSIST_SERVICE_URL
: http://persist.nango.internal:3007
.JOBS_SERVICE_URL
: http://jobs.nango.internal:3005
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Create each Task Definition.
Create an ECS service for each task definition to run and maintain the desired number of instances.
nango.internal
.nango-server
, nango-jobs
).nango-server
container to load balance.nango.internal
namespace created earlier.server
, jobs
, persist
, orchestrator
, runner
). This allows services to find each other at <service-name>.nango.internal
.Once the Nango Server service and ALB are running:
nango-alb
.http://ALB.DNS
). You should see the Nango interface.Step-by-step guide to deploy Nango on AWS ECS (Fargate)
Nango can be deployed on an AWS ECS cluster using AWS Fargate. Below are the detailed steps, based on common configuration practices, to get a Nango stack up and running. Before proceeding, it’s helpful to understand the core components of a Nango self-hosted deployment, which are detailed in the Nango Infrastructure Components documentation.
We will first set up the necessary AWS infrastructure, including a VPC, security groups, RDS PostgreSQL database, Elasticache and S3 bucket.
Then, we will configure an ECS cluster using AWS Fargate, define the necessary task definitions for Nango’s microservices, and create the corresponding ECS services.
Finally, we’ll set up a load balancer to expose the Nango server.
Remember to replace placeholder values with your actual configuration and adjust resource sizes based on your expected load. For further assistance, reach out to the Nango customer support.
A Virtual Private Cloud (VPC) is recommended to host the resources.
10.0.0.0/16
).0.0.0.0/0
). Egress should allow traffic to the ECS service security group.Store the Nango secrets securely.
nango/nango-encryption-key
).nango/elasticache-auth-token
).Nango requires a PostgreSQL database.
If you already have a PostgreSQL database (version 16.1 or higher recommended) that you want to use, you can skip the creation steps below.
postgresql://<user>:<password>@<host>:<port>/<database_name>
.aurora-postgresql
. Use a compatible version (>= 16.1).nango
.postgres
(or choose another).large
instance type is recommended).No
.Nango requires a Redis-compatible cache like Elasticache.
nango-cache-private-sng
.nango-valkey
.8.0
).6379
(default).cache.t3.small
).nango-cache-private-sng
created above.NANGO_REDIS_URL
env var.Nango may require an S3 bucket for storing integration-related data.
nango-integrations
).AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
securely.GetObject
, PutObject
, DeleteObject
, ListBucket
) limited to this specific bucket. These keys will be needed as environment variables for Nango services.nango-cluster
).An Application Load Balancer (ALB) is used to expose the Nango server service.
nango-server-tg-80
./health
nango-server-tg-3009
./
nango-alb
.Define the container configurations for each Nango service using Fargate.
Go to AWS ECS > Task Definitions.
Create New Task Definition:
awsvpc
.ecsTaskExecutionRole
or ensure one exists with permissions to pull images and write logs. It also needs permission to access the Secrets Manager secret for the encryption key.Define Containers: Create one task definition for each Nango service (Server, Jobs, Persist, Orchestrator, Runner), configuring the container settings within each:
Common Settings for all Containers:
nangohq/nango:<TAG>
(use a specific, stable tag, e.g., nangohq/nango:cbacc6a4fd4306a4245d774204a2b837e6f39599
).NANGO_ENTERPRISE
: true
NODE_ENV
: production
NODE_OPTIONS
: --max-old-space-size=N
, replace with value equals to 3/4 of task memoryNANGO_DATABASE_URL
: The database connection URL from RDS (use dynamic reference or Secrets Manager). Format: postgresql://<user>:<password>@<host>:<port>/<db_name>
.NANGO_ENCRYPTION_KEY
: Reference the value from the AWS Secrets Manager secret created earlier.NANGO_REDIS_URL
: Reference the Elasticache primary endpoint created earlier.NANGO_LOGS_ENABLED
: true
(Set to 'false'
to disable Nango logs).NANGO_LOGS_ES_URL
: Elasticsearch endpoint URL, required if NANGO_LOGS_ENABLED=true
. ex:https://my.elastic.cluster:9500
.NANGO_LOGS_ES_USER
: Your Elasticsearch username.NANGO_LOGS_ES_PWD
: Your Elasticsearch password.awslogs
driver pointing to a CloudWatch log group (e.g., ecs/nango
).Nango Server Container:
server
.["packages/server/entrypoint.sh"]
.SERVER_PORT
: 80
FLAG_SERVE_CONNECT_UI
: true
NANGO_SERVER_URL
: The public URL of the ALB (e.g., http://ALB.DNS
).NANGO_PUBLIC_SERVER_URL
: Same as NANGO_SERVER_URL
.NANGO_PUBLIC_CONNECT_URL
: The public URL of the ALB with port 3009 (e.g., http://ALB.DNS:3009
).SMTP_URL
: The url of your SMTP server (ex: smtps://username:password@my-stmp-server.com:465
)SMTP_FROM
: The email address used to send emailsAWS_BUCKET_NAME
: Name of the S3 bucket.AWS_ACCESS_KEY_ID
: Access key for S3 bucket user.AWS_SECRET_ACCESS_KEY
: Secret key for S3 bucket user.AWS_REGION
: AWS region for the S3 bucket.ORCHESTRATOR_SERVICE_URL
: http://orchestrator.nango.internal:3008
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Jobs Container:
jobs
.["node", "packages/jobs/dist/app.js"]
.ORCHESTRATOR_SERVICE_URL
: http://orchestrator.nango.internal:3008
.PERSIST_SERVICE_URL
: http://persist.nango.internal:3007
.RUNNER_TYPE
: REMOTE
RUNNER_SERVICE_URL
: http://runner.nango.internal:3006
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Persist Container:
persist
.["node", "packages/persist/dist/app.js"]
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Orchestrator Container:
orchestrator
.["node", "packages/orchestrator/dist/app.js"]
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Nango Runner Container:
runner
.["node", "packages/runner/dist/app.js"]
.RUNNER_NODE_ID
: 1
PERSIST_SERVICE_URL
: http://persist.nango.internal:3007
.JOBS_SERVICE_URL
: http://jobs.nango.internal:3005
.Task Definition JSON
The PLACEHOLDER values needs to be set manually.
Create each Task Definition.
Create an ECS service for each task definition to run and maintain the desired number of instances.
nango.internal
.nango-server
, nango-jobs
).nango-server
container to load balance.nango.internal
namespace created earlier.server
, jobs
, persist
, orchestrator
, runner
). This allows services to find each other at <service-name>.nango.internal
.Once the Nango Server service and ALB are running:
nango-alb
.http://ALB.DNS
). You should see the Nango interface.