Private Beta - Scalingo TCP Addon

This addon is currently in Private Beta. Ask the support to have early access.


By default, Scalingo will only let you run application that communicate via HTTP or HTTPS. Sometimes this is not enough and you need to have applications that can accept raw TCP connections.

This addon lets you deploy applications that can accept raw TCP connections.

Setup of the Addon

Provision the Addon

First, you need to add the TCP addon to your application. This can be done through the dashboard on the addons section of your app under the Network category.

Setup Configuration

In order to use the Scalingo TCP addon, you need to define a new container type. This can be done in your Procfile.

Here is a sample Procfile for a Node.js application:

web: npm start
tcp: npm run start-tcp

Contact your Application

When your application starts, a PORT environment variable is defined in your container. Your application must listen on this port in order to be accessible from the outside. This is the exact same mechanism and the exact same environment variable that the one used to expose a HTTP server in a web container.

Once up and running your application will be accessible at the URL defined by the TCP_URL environment variable.

This TCP_URL looks like: tcp://

You can find this environment variable on our dashboard or by using our CLI:

scalingo --app my-app env | grep TCP_URL

This URL is also accessible on the addon dashboard.

Your TCP containers might be restarted at any moment by our scheduler, this is done with 0 downtime, but the connections to the old containers are dropped. Hence your client must contain a retry policy in case a connection is dropped.

If you need to contact a tcp container from a web container, you must also use this URL, there is no direct link between your containers, every communication must pass via our load balancer. It’s the exact same thing if you need to contact a web container from a tcp container, you must use the public URL of the web container.

Application Restart and New Deployments

When a new version of the application is pushed or when the tcp containers are restarted, newly created tcp containers are started. TCP handshakes are then sent to your applications. Once a TCP handshake is successfull, newly incoming TCP connections will be sent to this container and old containers will receive a SIGTERM signal, notifying them to stop, see container-management for more informations.

The server application is responsible for closing opened connections with its clients once the the signal SIGTERM has been catched. If the server does not close the connections, the new rules will be updated and next packets will be dropped causing the clients to timeout.

Load Balancing

If you have multiple tcp containers running, Scalingo distributes connections to those containers. Our load balancer distributes connections during the TCP handshake. When established, the communication is always routed to the same server.

Rate Limiting

Your bandwidth to and from your containers is limited. This limit depends on your addon plan. This limit is expressed in packet per second per container. If a container gets over his limit, excess packets will be dropped.

Since the MTU is generally equal to 1500 bytes, you can do the conversion packet/s to byte/s by multiplying your rate limit by 1500.

If you have an addon with a limit of 1000 packet/s with 4 containers running, your bandwidth is:

1000 * 1500 = 1.5 MB/s for one container.

1.5 * 4 = 6 MB/s for all your containers.

A limit burst is granted for every container. This burst is equal to 10 times the limit, so if you have a limit of 10 packets/s, your burst will be set to 100 packets.


To be able to load balance tcp connections, connections are proxied to your containers via NAT. This process comes with a downside: the TCP source IP needs to be replaced by our front servers internal IP, this mean that a tcp container wont be able to access the real client IP. Thus, the device identification should be part of the protocol you designed over the TCP connection.


You can find a sample Node.js application that uses this addon to expose a MQTT server built with Mosca on Github.

schedule 23 Oct 2017