Skip to content

Commit e9292a2

Browse files
AitemAitem
authored
Merge pull request #22 from Aidbox/aidbox-with-proxy
aidbox proxy example
2 parents b9f9184 + 1cccfdf commit e9292a2

3 files changed

Lines changed: 242 additions & 0 deletions

File tree

‎aidbox-features/aidbox-outbound-proxy/README.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
features: [Proxy, Security, Network, Configuration, Environment variables]
3+
languages: [YAML]
4+
---
5+
# Using Aidbox with Outbound Proxy
6+
7+
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.
8+
9+
## Overview
10+
11+
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:
12+
13+
- **Network Isolation**: Run Aidbox in an internal network without direct internet access
14+
- **Proxy Configuration**: Route outbound HTTPS traffic through a Squid proxy
15+
- **Reverse Proxy Access**: Expose Aidbox through the proxy for external access
16+
17+
Common use cases include:
18+
19+
- Corporate environments requiring traffic inspection
20+
- Compliance requirements for logging all external communications
21+
- Security policies that restrict direct internet access
22+
- Environments where terminology servers or other external services must be accessed via proxy
23+
24+
## Architecture
25+
26+
This setup uses Docker networks to isolate Aidbox from external access while allowing it to reach the internet through a Squid proxy.
27+
28+
```mermaid
29+
graph LR
30+
subgraph external[External Network]
31+
internet((Internet))
32+
user((User))
33+
end
34+
subgraph internal[Internal Network]
35+
aidbox[Aidbox]
36+
postgres[(PostgreSQL)]
37+
end
38+
squid[Squid Proxy]
39+
40+
user -->|:8080| squid
41+
squid <-->|Reverse Proxy| aidbox
42+
aidbox -->|HTTPS via :3128| squid
43+
squid <-->|HTTPS| internet
44+
aidbox <--> postgres
45+
```
46+
47+
### Network Configuration
48+
49+
- **Internal Network**: Aidbox and PostgreSQL run on an isolated internal network with no direct internet access
50+
- **External Network**: Squid proxy has access to both internal and external networks
51+
- **Proxy Ports**:
52+
- Port `3128`: Forward proxy for outbound HTTPS traffic from Aidbox
53+
- Port `8080`: Reverse proxy for accessing Aidbox UI/API
54+
55+
## Prerequisites
56+
57+
- [Docker](https://www.docker.com/)
58+
- Clone the repository and navigate to the working directory:
59+
```sh
60+
git clone https://github.com/Aidbox/examples.git
61+
cd aidbox-features/aidbox-outbound-proxy
62+
```
63+
64+
## Up and Running
65+
66+
Below is a Docker Compose configuration ([docker-compose.yaml](./docker-compose.yaml)) that sets up:
67+
68+
1. A PostgreSQL database on the internal network
69+
2. Aidbox configured to use the proxy for outbound HTTPS traffic
70+
3. A Squid proxy server bridging internal and external networks
71+
72+
```shell
73+
docker-compose up
74+
```
75+
76+
### Configuration
77+
78+
Pay special attention to the `JAVA_OPTS` environment variable that configures the HTTPS proxy for Aidbox:
79+
80+
```yaml
81+
JAVA_OPTS: "-Dhttps.proxyHost=squid -Dhttps.proxyPort=3128"
82+
```
83+
84+
This Java system property tells Aidbox to route all outbound HTTPS connections through the Squid proxy.
85+
86+
#### Squid Proxy Configuration
87+
88+
The [squid.conf](./squid.conf) file configures Squid to:
89+
90+
1. **Forward Proxy** (port 3128): Handle outbound HTTPS traffic from Aidbox
91+
2. **Reverse Proxy** (port 8080): Provide access to Aidbox from external clients
92+
93+
Key configuration sections:
94+
95+
```squid
96+
# Forward proxy port
97+
http_port 3128
98+
99+
# Reverse proxy to Aidbox
100+
http_port 8080 accel vhost
101+
cache_peer aidbox parent 8080 0 no-query originserver name=aidbox
102+
```
103+
104+
## Usage Examples
105+
106+
### Initializing Aidbox
107+
108+
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.
109+
110+
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.
111+
112+
### Verifying Proxy Usage
113+
114+
To confirm that Aidbox is using the proxy, monitor Squid's access logs:
115+
116+
```shell
117+
docker-compose exec squid tail -f /var/log/squid/access.log
118+
```
119+
120+
## Additional Resources
121+
122+
- [Squid Proxy Documentation](http://www.squid-cache.org/Doc/)
123+
- [Java Networking and Proxies](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html)

‎aidbox-features/aidbox-outbound-proxy/docker-compose.yaml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
networks:
2+
internal:
3+
internal: true
4+
external:
5+
# Squid uses this to reach the internet
6+
internal: false
7+
8+
volumes:
9+
postgres_data: {}
10+
services:
11+
squid:
12+
image: ubuntu/squid:latest
13+
ports:
14+
- "3128:3128"
15+
- "8080:8080"
16+
volumes:
17+
- ./squid.conf:/etc/squid/squid.conf:ro
18+
networks:
19+
- internal
20+
- external
21+
postgres:
22+
image: docker.io/library/postgres:18
23+
volumes:
24+
- postgres_data:/var/lib/postgresql/18/docker:delegated
25+
command:
26+
- postgres
27+
- -c
28+
- shared_preload_libraries=pg_stat_statements
29+
networks:
30+
- internal
31+
environment:
32+
POSTGRES_USER: aidbox
33+
POSTGRES_PORT: "5432"
34+
POSTGRES_DB: aidbox
35+
POSTGRES_PASSWORD: kSH1rUEubE
36+
aidbox:
37+
image: healthsamurai/aidboxone:edge
38+
pull_policy: always
39+
depends_on:
40+
- postgres
41+
- squid
42+
networks:
43+
- internal
44+
environment:
45+
BOX_ADMIN_PASSWORD: Lz5squFqh4
46+
BOX_BOOTSTRAP_FHIR_PACKAGES: hl7.fhir.r4.core#4.0.1
47+
BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX: "#{:fhir-datetime}"
48+
BOX_DB_DATABASE: aidbox
49+
BOX_DB_HOST: postgres
50+
BOX_DB_PASSWORD: kSH1rUEubE
51+
BOX_DB_PORT: "5432"
52+
BOX_DB_USER: aidbox
53+
BOX_FHIR_BUNDLE_EXECUTION_VALIDATION_MODE: limited
54+
BOX_FHIR_COMPLIANT_MODE: "true"
55+
BOX_FHIR_CORRECT_AIDBOX_FORMAT: "true"
56+
BOX_FHIR_CREATEDAT_URL: https://aidbox.app/ex/createdAt
57+
BOX_FHIR_SCHEMA_VALIDATION: "true"
58+
BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS: "true"
59+
BOX_FHIR_SEARCH_CHAIN_SUBSELECT: "true"
60+
BOX_FHIR_SEARCH_COMPARISONS: "true"
61+
BOX_FHIR_TERMINOLOGY_ENGINE: legacy
62+
BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir
63+
BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL: https://tx.health-samurai.io/fhir
64+
BOX_MODULE_SDC_STRICT_ACCESS_CONTROL: "true"
65+
BOX_ROOT_CLIENT_SECRET: 14ZOifEdic
66+
BOX_RUNME_UUID: 694f00a6-b4b6-43e7-963e-8c88999b9198
67+
BOX_SEARCH_INCLUDE_CONFORMANT: "true"
68+
BOX_SECURITY_AUDIT_LOG_ENABLED: "true"
69+
BOX_SECURITY_DEV_MODE: "true"
70+
BOX_SETTINGS_MODE: read-write
71+
BOX_WEB_BASE_URL: http://localhost:8080
72+
BOX_WEB_PORT: 8080
73+
JAVA_OPTS: "-Dhttps.proxyHost=squid -Dhttps.proxyPort=3128"
74+
healthcheck:
75+
test: curl -f http://localhost:8080/health || exit 1
76+
interval: 5s
77+
timeout: 5s
78+
retries: 90
79+
start_period: 30s

‎aidbox-features/aidbox-outbound-proxy/squid.conf‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
http_port 3128
2+
http_port 8080 accel vhost
3+
4+
# Reverse proxy to aidbox
5+
cache_peer aidbox parent 8080 0 no-query originserver name=aidbox
6+
acl aidbox_access port 8080
7+
cache_peer_access aidbox allow aidbox_access
8+
cache_peer_access aidbox deny all
9+
10+
# Allow all Docker networks
11+
acl localnet src 10.0.0.0/8
12+
acl localnet src 172.16.0.0/12
13+
acl localnet src 192.168.0.0/16
14+
15+
# Safe ports
16+
acl SSL_ports port 443
17+
acl Safe_ports port 80
18+
acl Safe_ports port 443
19+
20+
# Allow CONNECT to SSL ports
21+
acl CONNECT method CONNECT
22+
23+
# Add 8080 as safe port for reverse proxy
24+
acl Safe_ports port 8080
25+
26+
# Deny requests to unsafe ports
27+
http_access deny !Safe_ports
28+
http_access deny CONNECT !SSL_ports
29+
30+
# Allow access from local networks
31+
http_access allow localnet
32+
33+
# Allow reverse proxy access from anywhere (for aidbox UI)
34+
http_access allow aidbox_access
35+
36+
# Deny all other access
37+
http_access deny all
38+
39+
# Logging
40+
access_log /var/log/squid/access.log squid

0 commit comments

Comments
 (0)