Proxy Environment

Surfly supports deployment in environments that use HTTP proxies for outbound connections. This is common in corporate networks where direct internet access is restricted and all outbound traffic must go through a proxy server.

Configuration Overview

Surfly doesn’t require special configuration for proxy support. Instead, it uses standard proxy environment variables that are configured at the system level. All Surfly containers will automatically inherit and use these proxy settings.

System-Level Proxy Configuration

Configure proxy settings by adding environment variables to your system’s /etc/environment file. This ensures all processes, including containerized services, use the proxy configuration.

Basic Proxy Setup

Edit the system environment file:

sudo vi /etc/environment

Add the following proxy configuration (replace with your actual proxy server details):

HTTP_PROXY=http://192.168.5.1:8080
HTTPS_PROXY=http://192.168.5.1:8080
NO_PROXY="localhost,127.0.0.1"

# Also include lowercase versions for compatibility
http_proxy=http://192.168.5.1:8080
https_proxy=http://192.168.5.1:8080
no_proxy="localhost,127.0.0.1"

Caution

Include Both Cases Always add both uppercase and lowercase versions of proxy variables. Different applications and libraries may look for either format, so including both ensures maximum compatibility.

Container-Specific Configuration

If you need to override proxy settings for specific containers, you can modify the container environment files:

Global Container Environment

Edit the main configuration file:

vi ~/surfly/config.env

Add proxy variables:

# Your existing config
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

# Proxy configuration
HTTP_PROXY=http://192.168.5.1:8080
HTTPS_PROXY=http://192.168.5.1:8080
NO_PROXY=localhost,127.0.0.1

Apply Configuration

After configuring proxy settings, apply them to your session and restart services:

System-Wide Changes

For system-wide environment changes to take effect, logout and log back in to apply the new configuration.

Restart Surfly Services

If Surfly is already running, restart services to pick up new proxy configuration:

systemctl --user restart ss-surfly.target

Verification

Verify that proxy settings are working correctly:

Test Outbound Connectivity

Test connectivity to Surfly domains through the proxy:

# Test registry access
curl -I https://registry.surfly.com

# Test build agent access
curl -I https://build-agent.surfly.com

Check Container Environment

Verify that containers are using proxy settings:

# Check environment variables in running container
podman exec ss-haproxy env | grep -i proxy

Troubleshooting

Common Issues

SSL/TLS Certificate Verification If your proxy uses custom certificates, you may need to add them to the system trust store:

# Copy proxy certificate to system trust directory
sudo cp proxy-cert.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

DNS Resolution Ensure DNS resolution works through your proxy:

# Test DNS resolution
nslookup registry.surfly.com
dig registry.surfly.com

Debugging Proxy Issues

Enable verbose logging to debug proxy connectivity:

# Set environment variables for debugging
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt

# Test with verbose output
curl -v -x http://192.168.5.1:8080 https://registry.surfly.com

Note

Corporate Network Integration Work with your network team to ensure proper firewall rules and proxy configuration for Surfly’s requirements. Document any custom proxy settings for future maintenance and troubleshooting.