> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/guides/system-connectivity/deploying-connectware-behind-a-corporate-proxy.md).

# Deploying Connectware Behind a Corporate Proxy

Deploy Connectware on a host whose Internet access is routed through a corporate proxy. This guide walks through the host, Docker, and Connectware proxy settings needed to install and run Connectware in such an environment.

## Prerequisites

* A valid [Connectware license](/2-4-1/documentation/installation-and-upgrades/licensing.md).
* [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/) installed on your system.
* The address and port of your corporate proxy.

The examples on this page use the following placeholders. Replace them with values from your environment:

* `${PROXY_HOST}` — hostname or IP address of the corporate proxy.
* `${PROXY_PORT}` — port the proxy listens on.

## Proxy Behavior Across Applications

Proxy configuration across applications can vary:

* Some tools recognize `http_proxy`, `https_proxy`, and `no_proxy` (lowercase).
* Others may use `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (uppercase).
* Some software may require both or use custom proxy settings.

General recommendations:

* Set both lowercase and uppercase variants of proxy variables.
* Avoid IP addresses unless known to be used directly by the application.
* Hostname resolution may fail under proxy settings unless explicitly configured.

## Configuration

### Verifying Host and Proxy Server Reachability

Confirm the host can reach the proxy server before configuring anything else:

{% code lineNumbers="true" %}

```bash
uname -a
ping -c 1 ${PROXY_HOST}
```

{% endcode %}

The `ping` command should report a successful reply with no packet loss.

### System-Wide Proxy Configuration

Apply proxy settings system-wide so every shell session inherits them:

1. Create a script in `/etc/profile.d/`. Shell scripts in this directory run at login for every user.

{% code lineNumbers="true" %}

```bash
sudo nano /etc/profile.d/proxy.sh
```

{% endcode %}

2. Add the following content and save the file:

{% code lineNumbers="true" %}

```bash
export http_proxy="http://${PROXY_HOST}:${PROXY_PORT}/"
export https_proxy="http://${PROXY_HOST}:${PROXY_PORT}/"
export no_proxy="127.0.0.1,localhost"
export HTTP_PROXY="http://${PROXY_HOST}:${PROXY_PORT}/"
export HTTPS_PROXY="http://${PROXY_HOST}:${PROXY_PORT}/"
export NO_PROXY="127.0.0.1,localhost"
```

{% endcode %}

3. Make the script executable:

{% code lineNumbers="true" %}

```bash
sudo chmod +x /etc/profile.d/proxy.sh
```

{% endcode %}

4. Open a new shell session or log out and back in to apply the changes. Verify that the variables are set:

{% code lineNumbers="true" %}

```bash
env | grep -i proxy
```

{% endcode %}

### Preserving Proxy Settings for Sudo

By default, `sudo` strips environment variables. Preserve the proxy variables for `sudo` invocations:

1. Create a sudoers drop-in file:

{% code lineNumbers="true" %}

```bash
sudo nano /etc/sudoers.d/env_keep_proxy
```

{% endcode %}

2. Add the following line and save the file:

{% code lineNumbers="true" %}

```bash
Defaults env_keep += "http_proxy https_proxy no_proxy HTTP_PROXY HTTPS_PROXY NO_PROXY"
```

{% endcode %}

### APT Proxy Configuration

On Debian-based systems, APT does not read the shell environment variables and needs its own proxy configuration. This step is not required to run Connectware, but without it APT cannot install software through the proxy.

1. Create an APT configuration file:

{% code lineNumbers="true" %}

```bash
sudo nano /etc/apt/apt.conf.d/80proxy
```

{% endcode %}

2. Add the following lines and save the file:

{% code lineNumbers="true" %}

```bash
Acquire::http::proxy "http://${PROXY_HOST}:${PROXY_PORT}/";
Acquire::https::proxy "http://${PROXY_HOST}:${PROXY_PORT}/";
Acquire::ftp::proxy "http://${PROXY_HOST}:${PROXY_PORT}/";
```

{% endcode %}

### Docker Daemon Proxy Setup

The Docker daemon needs its own proxy configuration to pull images from the Internet:

1. Create the systemd drop-in directory for the Docker service:

{% code lineNumbers="true" %}

```bash
sudo mkdir -p /etc/systemd/system/docker.service.d
```

{% endcode %}

2. Create the configuration file:

{% code lineNumbers="true" %}

```bash
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
```

{% endcode %}

3. Add the following content and save the file:

{% code lineNumbers="true" %}

```ini
[Service]
Environment="HTTP_PROXY=http://${PROXY_HOST}:${PROXY_PORT}/"
Environment="HTTPS_PROXY=http://${PROXY_HOST}:${PROXY_PORT}/"
Environment="NO_PROXY=localhost,127.0.0.1"
```

{% endcode %}

4. Reload systemd and restart Docker:

{% code lineNumbers="true" %}

```bash
sudo systemctl daemon-reload
sudo systemctl restart docker
```

{% endcode %}

5. Verify the configuration:

{% code lineNumbers="true" %}

```bash
sudo systemctl show --property=Environment docker
```

{% endcode %}

The output should list the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` values you set.

6. Test that Docker can reach the Internet through the proxy:

{% code lineNumbers="true" %}

```bash
docker pull hello-world
```

{% endcode %}

The command should complete with `Status: Downloaded newer image for hello-world:latest`.

### Container-Level Internet Access

Containers do not inherit the Docker daemon proxy settings. Configure proxy settings for containers globally through the Docker client config, or per container through environment variables.

To define global proxy settings for every container started by this user:

1. Create the Docker client configuration directory and the configuration file:

{% code lineNumbers="true" %}

```bash
mkdir -p ~/.docker
nano ~/.docker/config.json
```

{% endcode %}

2. Add the following content and save the file. Include the Connectware service names in `noProxy` so the containers can reach each other without going through the proxy:

{% code lineNumbers="true" %}

```json
{
  "proxies": {
    "default": {
      "httpProxy": "http://${PROXY_HOST}:${PROXY_PORT}/",
      "httpsProxy": "http://${PROXY_HOST}:${PROXY_PORT}/",
      "noProxy": "127.0.0.1,localhost,admin-web-app,auth-server,broker,container-manager,connectware,ingress-controller,nats,postgresql,protocol-mapper,service-manager,system-control-server,resource-status-tracking,topic-explorer,workbench"
    }
  }
}
```

{% endcode %}

### Configuring the Connectware Environment File

Set the proxy in the Connectware environment file before launching the stack. The `.env` file is located in your installation directory, by default `/opt/connectware/`.

1. Open the environment file:

{% code lineNumbers="true" %}

```bash
sudo nano /opt/connectware/.env
```

{% endcode %}

2. Add the following lines and save the file:

{% code lineNumbers="true" %}

```bash
# Proxy Configuration
CYBUS_PROXY=http://${PROXY_HOST}:${PROXY_PORT}/
CYBUS_NO_PROXY=127.0.0.1,localhost,admin-web-app,auth-server,broker,container-manager,connectware,ingress-controller,nats,postgresql,protocol-mapper,service-manager,system-control-server,resource-status-tracking,topic-explorer,workbench
```

{% endcode %}

## Verification

After applying the configuration, confirm that each layer can reach the Internet through the proxy:

* Run `env | grep -i proxy` and confirm the shell sees the proxy variables.
* Run `docker pull hello-world` and confirm the image pulls successfully.
* Start Connectware with `docker compose up -d` and confirm the auth-server logs show successful outbound calls when a feature that requires Internet access is exercised (for example, an SSO login).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-1/guides/system-connectivity/deploying-connectware-behind-a-corporate-proxy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.