TCP Gateway Addon
By default, Scalingo will only let you run applications 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-get TCP_URL
This URL is also accessible on the addon dashboard.
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 successful, 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 signal
SIGTERM is caught. 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
As described in the routing documentation, application nodes cannot receive HTTP/2 traffic. Thus, you need to deploy your application on the TCP Gateway:
tcp: <run your grpc app>
Your gRPC server will be accessible at the address in
Don’t forget to remove unused web / worker nodes on your app.
There’s no rate limiting in place. It may be put in place later.
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.