Skip to content

Commit 04996cf

Browse files
ammar-agentammar-agent
committed
docs: Add Dockerfile example and Docker documentation
- Add Dockerfile to examples/ directory - Create comprehensive Docker documentation in docs/advanced/docker.md - Update SUMMARY.md to include Docker page - Covers building, running, configuring clients, and rule examples - Relates to PR #94
1 parent dec08ee commit 04996cf

File tree

3 files changed

+270
-0
lines changed

3 files changed

+270
-0
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
- [TLS Interception](./advanced/tls-interception.md)
2121
- [DNS Exfiltration](./advanced/dns-exfiltration.md)
2222
- [Server Mode](./advanced/server-mode.md)
23+
- [Docker](./advanced/docker.md)
2324

2425
---
2526

‎docs/advanced/docker.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Docker
2+
3+
httpjail can run as a standalone proxy server in a Docker container, perfect for team-wide policy enforcement or testing. An example Dockerfile is provided in the [`examples/`](https://github.com/coder/httpjail/tree/main/examples) directory.
4+
5+
## Building the Image
6+
7+
The example Dockerfile downloads httpjail from GitHub releases and runs as a non-root user (UID 1000). Multi-arch builds are supported for `linux/amd64` and `linux/arm64`.
8+
9+
**Build for your current platform:**
10+
11+
```bash
12+
cd examples/
13+
docker build -t httpjail:latest .
14+
```
15+
16+
**Build for a specific platform:**
17+
18+
```bash
19+
# For amd64 (x86_64)
20+
docker build --platform linux/amd64 -t httpjail:amd64 .
21+
22+
# For arm64 (aarch64)
23+
docker build --platform linux/arm64 -t httpjail:arm64 .
24+
```
25+
26+
**Build and push multi-arch image to a registry:**
27+
28+
```bash
29+
# Create and use a new buildx builder (one-time setup)
30+
docker buildx create --name multiarch --use
31+
32+
# Build and push for both architectures
33+
docker buildx build --platform linux/amd64,linux/arm64 \
34+
-t your-registry/httpjail:latest \
35+
--push .
36+
37+
# Or build and load locally (single platform only)
38+
docker buildx build --platform linux/amd64 \
39+
-t httpjail:latest \
40+
--load .
41+
```
42+
43+
> **Note:** Multi-arch builds require [Docker Buildx](https://docs.docker.com/build/buildx/). The `--load` flag only works with single-platform builds; use `--push` for multi-platform images.
44+
45+
## Running the Container
46+
47+
**Basic usage with default allow-all rule:**
48+
49+
```bash
50+
docker run -d --name httpjail \
51+
-p 8080:8080 -p 8443:8443 \
52+
httpjail:latest
53+
```
54+
55+
**With persistent certificates:**
56+
57+
```bash
58+
mkdir -p ./httpjail-certs
59+
docker run -d --name httpjail \
60+
-p 8080:8080 -p 8443:8443 \
61+
-v ./httpjail-certs:/home/httpjail/.config/httpjail \
62+
httpjail:latest
63+
```
64+
65+
**With custom rules:**
66+
67+
```bash
68+
# Create your custom rule file
69+
cat > my-rules.js <<'EOF'
70+
// Allow only specific domains
71+
const allowed = ['github.com', 'api.github.com', 'npmjs.org'];
72+
allowed.includes(r.host)
73+
EOF
74+
75+
# Run with custom rules (overrides default rules.js)
76+
docker run -d --name httpjail \
77+
-p 8080:8080 -p 8443:8443 \
78+
-v ./httpjail-certs:/home/httpjail/.config/httpjail \
79+
-v ./my-rules.js:/rules/rules.js:ro \
80+
httpjail:latest
81+
```
82+
83+
**With additional verbosity:**
84+
85+
```bash
86+
docker run -d --name httpjail \
87+
-p 8080:8080 -p 8443:8443 \
88+
httpjail:latest --server --js-file /rules/rules.js -vv --request-log /dev/stderr
89+
```
90+
91+
## Configuring Clients
92+
93+
After starting the container, configure your applications to use the proxy:
94+
95+
```bash
96+
export HTTP_PROXY=http://localhost:8080
97+
export HTTPS_PROXY=http://localhost:8443
98+
```
99+
100+
For HTTPS to work, clients need to trust the CA certificate. Extract it from the container:
101+
102+
```bash
103+
# Extract CA certificate
104+
docker cp httpjail:/home/httpjail/.config/httpjail/ca-cert.pem ./ca-cert.pem
105+
106+
# Configure client
107+
export SSL_CERT_FILE=$PWD/ca-cert.pem
108+
109+
# Test
110+
curl https://github.com
111+
```
112+
113+
Alternatively, install the certificate system-wide:
114+
115+
```bash
116+
# Linux
117+
sudo cp ca-cert.pem /usr/local/share/ca-certificates/httpjail.crt
118+
sudo update-ca-certificates
119+
120+
# macOS
121+
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca-cert.pem
122+
```
123+
124+
## Viewing Logs
125+
126+
Request logs are sent to stdout by default (visible in `docker logs`):
127+
128+
```bash
129+
docker logs -f httpjail
130+
```
131+
132+
Log format: `<timestamp> <+/-> <METHOD> <URL>` where `+` means allowed and `-` means blocked.
133+
134+
## JavaScript Rule Examples
135+
136+
The default rule (`true`) allows all traffic. Here are more useful examples:
137+
138+
**Allowlist specific domains:**
139+
140+
```javascript
141+
const allowed = ['github.com', 'api.github.com', 'npmjs.org'];
142+
allowed.includes(r.host)
143+
```
144+
145+
**Block specific paths:**
146+
147+
```javascript
148+
// Allow all except admin paths
149+
!r.path.startsWith('/admin')
150+
```
151+
152+
**Size limits:**
153+
154+
```javascript
155+
// Allow GET requests under 10MB
156+
if (r.method === 'GET') {
157+
({allow: {max_tx_bytes: 10 * 1024 * 1024}})
158+
} else {
159+
false // Block non-GET
160+
}
161+
```
162+
163+
**Custom deny messages:**
164+
165+
```javascript
166+
if (r.host === 'malicious.com') {
167+
({allow: false, deny_message: 'Blocked: Known malicious domain'})
168+
} else {
169+
true
170+
}
171+
```
172+
173+
**Complex policies:**
174+
175+
```javascript
176+
// Allow GitHub and NPM GET requests, deny everything else
177+
const trustedDomains = ['github.com', 'api.github.com', 'npmjs.org', 'registry.npmjs.org'];
178+
const isTrusted = trustedDomains.includes(r.host);
179+
const isSafeMethod = ['GET', 'HEAD'].includes(r.method);
180+
181+
isTrusted && isSafeMethod
182+
```
183+
184+
See the [JavaScript rule engine](../guide/rule-engines/javascript.md) documentation for complete reference.
185+
186+
## Security Notes
187+
188+
- The container runs as non-root user (UID 1000)
189+
- Server mode does NOT provide network isolation (no namespaces)
190+
- Applications must be configured to use the proxy (HTTP_PROXY/HTTPS_PROXY)
191+
- The Docker image supports both `linux/amd64` (x86_64) and `linux/arm64` (aarch64) architectures
192+
- Certificates are auto-generated on first run if not provided via volume mount

‎examples/Dockerfile‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
FROM debian:13-slim
2+
3+
LABEL org.opencontainers.image.title="httpjail" \
4+
org.opencontainers.image.description="HTTP/HTTPS proxy with JavaScript-based request filtering" \
5+
org.opencontainers.image.version="0.6.0" \
6+
org.opencontainers.image.source="https://github.com/coder/httpjail" \
7+
org.opencontainers.image.licenses="CC0-1.0"
8+
9+
# Install CA certificates for TLS connections
10+
RUN apt-get update && \
11+
apt-get install -y --no-install-recommends ca-certificates wget && \
12+
rm -rf /var/lib/apt/lists/*
13+
14+
# Create non-root user
15+
RUN useradd -u 1000 -m -s /bin/bash httpjail
16+
17+
# Download and install httpjail binary from GitHub releases
18+
# Supports multi-arch builds (amd64 and arm64)
19+
ARG TARGETARCH
20+
RUN set -ex; \
21+
case "${TARGETARCH}" in \
22+
amd64) HTTPJAIL_ARCH="x86_64" ;; \
23+
arm64) HTTPJAIL_ARCH="aarch64" ;; \
24+
*) echo "Unsupported architecture: ${TARGETARCH}" && exit 1 ;; \
25+
esac; \
26+
wget -q https://github.com/coder/httpjail/releases/download/v0.5.1/httpjail-0.5.1-linux-${HTTPJAIL_ARCH}.tar.gz && \
27+
tar -xzf httpjail-0.5.1-linux-${HTTPJAIL_ARCH}.tar.gz && \
28+
mv httpjail-0.5.1-linux-${HTTPJAIL_ARCH}/httpjail /usr/local/bin/httpjail && \
29+
chmod +x /usr/local/bin/httpjail && \
30+
rm -rf httpjail-0.5.1-linux-${HTTPJAIL_ARCH}.tar.gz httpjail-0.5.1-linux-${HTTPJAIL_ARCH}
31+
32+
# Create directory for rules
33+
RUN mkdir -p /rules && \
34+
chown -R httpjail:httpjail /rules
35+
36+
# Create default allow-all rule example
37+
# This can be overridden by bind-mounting a custom rule file
38+
RUN echo '// Default allow-all rule\n\
39+
// The request object (r) has these properties:\n\
40+
// r.url - Full URL\n\
41+
// r.method - HTTP method (GET, POST, etc.)\n\
42+
// r.host - Hostname\n\
43+
// r.scheme - URL scheme (http/https)\n\
44+
// r.path - URL path\n\
45+
//\n\
46+
// Return true to allow, false to deny\n\
47+
// Or return {allow: false, deny_message: "Custom message"}\n\
48+
// Or return {allow: {max_tx_bytes: 1024}} for size limits\n\
49+
\n\
50+
(function() {\n\
51+
// Your custom rules here\n\
52+
return true;\n\
53+
})();\n\
54+
' > /rules/rules.js && \
55+
chown httpjail:httpjail /rules/rules.js
56+
57+
# Switch to non-root user
58+
USER httpjail
59+
60+
# Create config directory for certificates (will be auto-generated if not mounted)
61+
RUN mkdir -p /home/httpjail/.config/httpjail
62+
63+
# Environment variables for server mode
64+
# Bind to all interfaces (0.0.0.0) for Docker accessibility
65+
ENV HTTPJAIL_HTTP_BIND=0.0.0.0:8080 \
66+
HTTPJAIL_HTTPS_BIND=0.0.0.0:8443
67+
68+
# Expose proxy ports
69+
EXPOSE 8080/tcp 8443/tcp
70+
71+
# Declare volumes for certificates and rules
72+
# Certificates are stored at /home/httpjail/.config/httpjail/
73+
VOLUME ["/home/httpjail/.config/httpjail", "/rules"]
74+
75+
# Set entrypoint and default command
76+
ENTRYPOINT ["httpjail"]
77+
CMD ["--server", "--js-file", "/rules/rules.js", "--request-log", "/dev/stdout"]

0 commit comments

Comments
 (0)