Running Cybus Connectware behind a Corporate Proxy

Prerequisites

In this lesson we will set up a local Cybus Connectware Instance which only has internet connection via a corporate proxy.

As a prerequisite, it is necessary to have Docker and Docker Compose installed on your system as well as a valid Connectware License on hand.

You can also install Docker and Docker Compose during this lesson, as you probably need some of the explained settings for the installation to work.

We assume you have at least a basic understanding of Docker and Linux. If you want to refresh your knowledge, we recommend looking at the lesson Docker Basics.
Explaining Linux would be far out of scope for this lesson, but it’s likely an answer to any Linux related question is out there on the internet.
Anyway, if you read carefully the listed commands should work with only minor adjustments.

Introduction

If you are unlucky and find yourself behind a Corporate Proxy, things might get a little bit more complicated and unpredictable then during a usual installation. This guide is intended to pinpoint a few possible pitfalls and tries to demystify the behavior of different proxy settings.

First of all, it is important to know that there is no de facto standard when dealing with the various environment variables for proxy settings.
Some applications might use the environment variables like http_proxy, https_proxy and no_proxy (all lowercase), whereas others might use them in all caps like HTTP_PROXY and so on. Some applications even consider both and prioritize one over the other and some do have their own way of proxy configuration.
When it comes to the actual environment variable values things are getting even worse.
If you are interested to read more on this topic, there is a good article over at GitLab. 

There are a few takeaways:

• Do configure both variables, the all caps and the all lowercase one
• Do not use IP Addresses as long as you are sure they are explicitly used by the application
• Proxying decisions are likely to not resolve any hostnames

With that in mind, I will guide you through configuring your system, Docker and Cybus Connectware. Not all of these steps are mandatory and may differ a bit depending on your operating system and the configuration of your proxy server.

System Configuration

For the purpose of writing this, I am using Debian 11 and a Proxy Server without authentication and restrictions.

The IP address of the Proxy Server in my case is 192.168.56.103 and the port is 8080. Make sure to adjust these settings to your individual ones.

Getting Host Information

Just to be transparent, this is what I am running on.

$ uname -a
Code language: YAML (yaml)

Linux cybus 5.10.0-13-amd64 #1 SMP Debian 5.10.106-1 (2022-03-17) x86_64 GNU/Linux
Code language: YAML (yaml)

Checking Proxy Server Reachability

As already mentioned, for me the Proxy Server is reachable on 192.168.56.103, so I am going to quickly check if I am able to reach it.

$ ping -c 1 192.168.56.103
Code language: YAML (yaml)

On a reachable server the output should look something like this.

PING 192.168.56.103 (192.168.56.103) 56(84) bytes of data.
64 bytes from 192.168.56.103: icmp_seq=1 ttl=64 time=0.204 ms

--- 192.168.56.103 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.204/0.204/0.204/0.000 ms
Code language: YAML (yaml)

Setting System Wide Proxy

For most applications it is sufficient to set a couple of proxy environment variables.
However this is not a requirement for running Cybus Connectware.
If you are going to use the Cybus Connectware Installation Script from this article, it is recommended to follow the instructions below.

First we are going to create a new file, which will contain our proxy settings.
The /etc/profile.d directory holds shell scripts that are likely to be executed at launch of your shell.

$ sudo nano /etc/profile.d/proxy.sh
Code language: YAML (yaml)

This is a basic example configuration. Adjust this to your needs. If these settings are recognized by any application, all traffic except for loopbacks will be forwarded to the proxy server. This even applies to servers within the same network.

export http_proxy="http://192.168.56.103:8080/"
export https_proxy="http://192.168.56.103:8080/"
export no_proxy="127.0.0.1,localhost"

export HTTP_PROXY="http://192.168.56.103:8080/"
export HTTPS_PROXY="http://192.168.56.103:8080/"
export NO_PROXY="127.0.0.1,localhost"
Code language: YAML (yaml)

Next we are going to make the script executable.

$ sudo chmod +x /etc/profile.d/proxy.sh
Code language: YAML (yaml)

If you log out of your shell and back in, all the settings should be applied. You can verify like this:

$ env | grep -i proxy
Code language: YAML (yaml)

Persist Proxy Settings for Sudo

Even if you have followed the instructions above your settings will not persist for any sudo-command. You can quickly observe this by running:

$ sudo env
Code language: YAML (yaml)

To fix this you can edit your configuration for sudo.

$ sudo nano /etc/sudoers.d/env_keep_proxy
Code language: YAML (yaml)

The content of the file should look like this:

Defaults        env_keep += "http_proxy https_proxy no_proxy HTTP_PROXY HTTPS_PROXY NO_PROXY"
Code language: YAML (yaml)

Verify your changes:

$ sudo env
Code language: YAML (yaml)

Set Proxy for APT Package Manager

The APT package manager application on Debian Systems has its own set of variables for proxy configuration. You can configure the proxy like this.
Doing this is again not required for running Cybus Connectware, but without this you won’t be able to install any software using APT.

$ sudo nano /etc/apt/apt.conf.d/80proxy
Code language: YAML (yaml)

Acquire::http::proxy "http://192.168.56.103:8080/";
Acquire::https::proxy "http://192.168.56.103:8080/";
Acquire::ftp::proxy "http://192.168.56.103:8080/";
Code language: YAML (yaml)

If you don’t have Docker and Docker Compose installed already, you should now be able to do so. 

Docker Daemon

Setting the Proxy Server for the Docker Daemon is mandatory if you want to download any Docker Images from the internet. This includes all Cybus Connectware related images from registry.cybus.io as well as images from Docker Hub.

The settings applied to the daemon do not affect the settings of any executed container.

Below are all the required steps. A full documentation can be found at https://docs.docker.com/config/daemon/systemd/

Create a systemd drop-in directory for the docker service:

$ sudo mkdir -p /etc/systemd/system/docker.service.d
Code language: YAML (yaml)

$ sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
Code language: YAML (yaml)

[Service]
Environment="HTTP_PROXY=http://192.168.56.103:8080/"
Environment="HTTPS_PROXY=http://192.168.56.103:8080/"
Environment="NO_PROXY=localhost,127.0.0.1"
Code language: YAML (yaml)

Flush the changes and restart Docker:

$ sudo systemctl daemon-reload
$ sudo systemctl restart docker
Code language: YAML (yaml)

Confirming the properties:

$ sudo systemctl show --property=Environment docker
Code language: YAML (yaml)

Should show something like this:

Environment=HTTP_PROXY=http://192.168.56.103:8080/ HTTPS_PROXY=http://192.168.56.103:8080/ NO_PROXY=localhost,127.0.0.1
Code language: YAML (yaml)

Testing image download from Docker Hub

$ docker pull hello-world
Code language: YAML (yaml)

Using default tag: latest
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:10d7d58d5ebd2a652f4d93fdd86da8f265f5318c6a73cc5b6a9798ff6d2b2e67
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest
Code language: YAML (yaml)

Docker Container

If you need internet access from within any executed container you can globally set the proxy environment variables. Docker will pass these variables to every container. This is not necessary or recommended. You are always free to pass these environment variables manually on container startup as needed.

If you choose to go this way, you can read more at Docker https://docs.docker.com/network/proxy/

For Cybus Connectware to run properly, it is required to list all Cybus Connectware Container Names in the noProxy property. This is because the microservices need to be able to communicate between each other.

$ mkdir -p ~/.docker
Code language: YAML (yaml)

$ nano ~/.docker/config.json
Code language: YAML (yaml)

{
"proxies":
{
  "default":
  {
    "httpProxy": "<a href="http://192.168.56.103:8080/%22" target="_blank" rel="noreferrer noopener">http://192.168.56.103:8080/"</a>,
    "httpsProxy": "<a href="http://192.168.56.103:8080/%22" target="_blank" rel="noreferrer noopener">http://192.168.56.103:8080/"</a>,
    "noProxy": "127.0.0.1,localhost,admin-web-app,auth-server,broker,container-manager,connectware,ingress-controller,postgresql,protocol-mapper,service-manager,system-control-server,workbench"
  }
}
}
Code language: YAML (yaml)

Connectware Configuration

If you have successfully followed the steps above, you should be able to install Cybus Connectware just like on any other system https://www.cybus.io/learn/installing-the-connectware/.

Before starting Cybus Connectware there is one additional step to do. We have to announce the Proxy Server to Cybus Connectware by adjusting the corresponding environment file.
By default the environment file is located in your installation directory.

$ sudo nano /opt/connectware/.env
Code language: YAML (yaml)

If you are prompted with an empty file, you are not in your Cybus Connectware Installation Directory.

The part for the proxy configuration should look something like this:

# Proxy Configuration
CYBUS_PROXY=http://192.168.56.103:8080/CYBUS_NO_PROXY=
Code language: YAML (yaml)