Deploying to servers in a private network

Using a deployment service such as DeployHQ to automate your deployment process is very convenient, but it can be a troublesome process to set up if you don't have direct access to the destination server. This is most common in situations where the server is within a private network — behind a firewall, on a VPN, or otherwise unreachable from the public internet.

If you're looking for a broader overview of deployment strategies for private networks, including firewall configuration and VPN-based approaches, see our companion guide: Deploying to a Private Network: A Guide to Using DeployHQ Behind a Firewall.

The Solution

Fortunately, we've created our own application, the DeployHQ Agent, that is designed with this use case in mind. The Agent is a lightweight application that runs on a server in your network, keeping a persistent, secure connection open to our infrastructure and allowing, optionally, access to other servers in the same network.

Because the agent acts as a proxy, you can use it to connect via any supported protocol, whether that's FTP, SSH/SFTP, or even S3. If you're new to SSH-based deployments, you may also find our guide on OpenSSH on Windows helpful.

In this guide, we'll be setting up the DeployHQ Agent on an Ubuntu server, but specific guides for other operating systems can be found when you're setting up the agent in your account.

Installing the DeployHQ Agent

To get started, you'll need to head to Settings -> Network Agents in your DeployHQ account, then click the New Network Agent button:

You'll need Ruby 2.7 or above installed on your system to use the DeployHQ Agent. You can install it and the required dependencies using the commands below:

$ sudo apt install ruby ruby-dev build-essential

Next, install the Deploy Agent gem:

$ gem install deploy-agent

Then, start the setup process to generate a code to verify the Agent in your DeployHQ account, and also add optional IP addresses that the agent can connect to in your network:

$ deploy-agent setup

This tool will assist you in generating a certificate for your Deploy agent.
Please enter a name for this agent.
Agent Name: DeployHQ Agent

Certificate has been successfully generated and installed.

By default this utility only allows connections from DeployHQ to localhost.
To to deploy to other hosts or networks enter their addresses below:
IP Address [leave blank to finish]: 10.0.2.111
IP Address [leave blank to finish]:

You can now associate this Agent with your Deploy account.
Browse to Settings -> Agents in your account and enter the code below:

 >> AAAABBBB <<

Once you've verified the agent, start it on your server:

$ deploy-agent start
Deploy agent started. Process ID 25444

Then click Complete Agent Setup back in DeployHQ to finish.

Once the setup process has finished, you'll find the agent in your list, with a status showing as online.

Connecting to a server using the agent

Now your agent is running, you can add a new server to any project in your account and choose to connect using it.

Head to your project, then the Servers and Groups page. Click New Server, then enter a name and select a protocol — in this case, we'll choose SSH:

Enter the hostname as localhost if you're connecting to the same machine as that running the agent, or the private IP address of any servers you've allowed. The rest of the information can be entered as normal.

Click Create Server at the bottom of the page, then you can start deploying to it! If you need to deploy to multiple destinations, check out Deploying to multiple servers at the same time.

Further reading

There are a number of useful things to note when using the agent:

• The server running the agent only needs to be able to connect to agent.deployhq.com via TCP port 7777, and does not need to accept incoming connections. Once a secure TLS connection is established, this is persisted, and all data is routed through this connection.
• The agent by default only allows access to the machine it's installed on, but you can modify the ~/.deploy/agent.access file to allow connections to additional destination servers within your network. You can specify individual IP addresses, hostnames, or CIDR ranges (e.g. 192.168.1.0/24). After changes are made to agent.access, you'll need to restart it using the deploy-agent restart command.
• For more detailed configuration options and troubleshooting, see the official Network Agents documentation.

Once your agent is running, consider reviewing Practical Security Tips for Smarter Deployments and Keeping your DeployHQ account secure to ensure your deployment pipeline is properly hardened. You might also want to build a full CI/CD pipeline around your deployments.

Ready to automate your deployments? Sign up for DeployHQ and get started in minutes. If you have any questions, reach out to us at support@deployhq.com or on Twitter/X @deployhq.