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
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
Once up and running your application will be accessible at the URL defined by
TCP_URL environment variable.
TCP_URL looks like:
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
Application Restart and New Deployments
When a new version of the application is pushed or when the
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
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.
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
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
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
You can find a sample Node.js application that uses this addon to expose a MQTT server built with Mosca on Github.