Skip to content

aidbox proxy example #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aitem merged 2 commits into from
Jan 12, 2026
Merged

aidbox proxy example #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d593086
aidbox proxy example
aleksandrkislitsyn Jan 9, 2026
1cccfdf
remove comment
aleksandrkislitsyn Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions aidbox-features/aidbox-outbound-proxy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
---
features: [Proxy, Security, Network, Configuration, Environment variables]
languages: [YAML]
---
# Using Aidbox with Outbound Proxy

This guide demonstrates how to configure Aidbox to route outbound HTTPS traffic through a proxy server (Squid). This is useful in enterprise environments where all external traffic must go through a corporate proxy for security, compliance, or monitoring purposes.

## Overview

In many enterprise environments, direct internet access is restricted and all outbound traffic must be routed through a proxy server. This example shows how to:

- **Network Isolation**: Run Aidbox in an internal network without direct internet access
- **Proxy Configuration**: Route outbound HTTPS traffic through a Squid proxy
- **Reverse Proxy Access**: Expose Aidbox through the proxy for external access

Common use cases include:

- Corporate environments requiring traffic inspection
- Compliance requirements for logging all external communications
- Security policies that restrict direct internet access
- Environments where terminology servers or other external services must be accessed via proxy

## Architecture

This setup uses Docker networks to isolate Aidbox from external access while allowing it to reach the internet through a Squid proxy.

```mermaid
graph LR
subgraph external[External Network]
internet((Internet))
user((User))
end
subgraph internal[Internal Network]
aidbox[Aidbox]
postgres[(PostgreSQL)]
end
squid[Squid Proxy]

user -->|:8080| squid
squid <-->|Reverse Proxy| aidbox
aidbox -->|HTTPS via :3128| squid
squid <-->|HTTPS| internet
aidbox <--> postgres
```

### Network Configuration

- **Internal Network**: Aidbox and PostgreSQL run on an isolated internal network with no direct internet access
- **External Network**: Squid proxy has access to both internal and external networks
- **Proxy Ports**:
- Port `3128`: Forward proxy for outbound HTTPS traffic from Aidbox
- Port `8080`: Reverse proxy for accessing Aidbox UI/API

## Prerequisites

- [Docker](https://www.docker.com/)
- Clone the repository and navigate to the working directory:
```sh
git clone https://github.com/Aidbox/examples.git
cd aidbox-features/aidbox-outbound-proxy
```

## Up and Running

Below is a Docker Compose configuration ([docker-compose.yaml](./docker-compose.yaml)) that sets up:

1. A PostgreSQL database on the internal network
2. Aidbox configured to use the proxy for outbound HTTPS traffic
3. A Squid proxy server bridging internal and external networks

```shell
docker-compose up
```

### Configuration

Pay special attention to the `JAVA_OPTS` environment variable that configures the HTTPS proxy for Aidbox:

```yaml
JAVA_OPTS: "-Dhttps.proxyHost=squid -Dhttps.proxyPort=3128"
```

This Java system property tells Aidbox to route all outbound HTTPS connections through the Squid proxy.

#### Squid Proxy Configuration

The [squid.conf](./squid.conf) file configures Squid to:

1. **Forward Proxy** (port 3128): Handle outbound HTTPS traffic from Aidbox
2. **Reverse Proxy** (port 8080): Provide access to Aidbox from external clients

Key configuration sections:

```squid
# Forward proxy port
http_port 3128

# Reverse proxy to Aidbox
http_port 8080 accel vhost
cache_peer aidbox parent 8080 0 no-query originserver name=aidbox
```

## Usage Examples

### Initializing Aidbox

1. Navigate to [Aidbox UI](http://localhost:8080) and [initialize](https://docs.aidbox.app/getting-started/run-aidbox-locally#id-4.-activate-your-aidbox-instance) the Aidbox instance.

The initialization process requires a connection to access to the package registry to download the FHIR core package - that will go through the proxy. If you restart Aidbox it will connect to the license server to validate your license - that will go through the proxy.

### Verifying Proxy Usage

To confirm that Aidbox is using the proxy, monitor Squid's access logs:

```shell
docker-compose exec squid tail -f /var/log/squid/access.log
```

## Additional Resources

- [Squid Proxy Documentation](http://www.squid-cache.org/Doc/)
- [Java Networking and Proxies](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html)
79 changes: 79 additions & 0 deletions aidbox-features/aidbox-outbound-proxy/docker-compose.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
networks:
internal:
internal: true
external:
# Squid uses this to reach the internet
internal: false

volumes:
postgres_data: {}
services:
squid:
image: ubuntu/squid:latest
ports:
- "3128:3128"
- "8080:8080"
volumes:
- ./squid.conf:/etc/squid/squid.conf:ro
networks:
- internal
- external
postgres:
image: docker.io/library/postgres:18
volumes:
- postgres_data:/var/lib/postgresql/18/docker:delegated
command:
- postgres
- -c
- shared_preload_libraries=pg_stat_statements
networks:
- internal
environment:
POSTGRES_USER: aidbox
POSTGRES_PORT: "5432"
POSTGRES_DB: aidbox
POSTGRES_PASSWORD: kSH1rUEubE
aidbox:
image: healthsamurai/aidboxone:edge
pull_policy: always
depends_on:
- postgres
- squid
networks:
- internal
environment:
BOX_ADMIN_PASSWORD: Lz5squFqh4
BOX_BOOTSTRAP_FHIR_PACKAGES: hl7.fhir.r4.core#4.0.1
BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX: "#{:fhir-datetime}"
BOX_DB_DATABASE: aidbox
BOX_DB_HOST: postgres
BOX_DB_PASSWORD: kSH1rUEubE
BOX_DB_PORT: "5432"
BOX_DB_USER: aidbox
BOX_FHIR_BUNDLE_EXECUTION_VALIDATION_MODE: limited
BOX_FHIR_COMPLIANT_MODE: "true"
BOX_FHIR_CORRECT_AIDBOX_FORMAT: "true"
BOX_FHIR_CREATEDAT_URL: https://aidbox.app/ex/createdAt
BOX_FHIR_SCHEMA_VALIDATION: "true"
BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS: "true"
BOX_FHIR_SEARCH_CHAIN_SUBSELECT: "true"
BOX_FHIR_SEARCH_COMPARISONS: "true"
BOX_FHIR_TERMINOLOGY_ENGINE: legacy
BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir
BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL: https://tx.health-samurai.io/fhir
BOX_MODULE_SDC_STRICT_ACCESS_CONTROL: "true"
BOX_ROOT_CLIENT_SECRET: 14ZOifEdic
BOX_RUNME_UUID: 694f00a6-b4b6-43e7-963e-8c88999b9198
BOX_SEARCH_INCLUDE_CONFORMANT: "true"
BOX_SECURITY_AUDIT_LOG_ENABLED: "true"
BOX_SECURITY_DEV_MODE: "true"
BOX_SETTINGS_MODE: read-write
BOX_WEB_BASE_URL: http://localhost:8080
BOX_WEB_PORT: 8080
JAVA_OPTS: "-Dhttps.proxyHost=squid -Dhttps.proxyPort=3128"
healthcheck:
test: curl -f http://localhost:8080/health || exit 1
interval: 5s
timeout: 5s
retries: 90
start_period: 30s
40 changes: 40 additions & 0 deletions aidbox-features/aidbox-outbound-proxy/squid.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
http_port 3128
http_port 8080 accel vhost

# Reverse proxy to aidbox
cache_peer aidbox parent 8080 0 no-query originserver name=aidbox
acl aidbox_access port 8080
cache_peer_access aidbox allow aidbox_access
cache_peer_access aidbox deny all

# Allow all Docker networks
acl localnet src 10.0.0.0/8
acl localnet src 172.16.0.0/12
acl localnet src 192.168.0.0/16

# Safe ports
acl SSL_ports port 443
acl Safe_ports port 80
acl Safe_ports port 443

# Allow CONNECT to SSL ports
acl CONNECT method CONNECT

# Add 8080 as safe port for reverse proxy
acl Safe_ports port 8080

# Deny requests to unsafe ports
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports

# Allow access from local networks
http_access allow localnet

# Allow reverse proxy access from anywhere (for aidbox UI)
http_access allow aidbox_access

# Deny all other access
http_access deny all

# Logging
access_log /var/log/squid/access.log squid