add docs for proxies and add settings.xml in proxy setup

jbangdev · Oct 25, 2023 · 6849a77 · 6849a77
1 parent 8234811
commit 6849a77
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 4 deletions.
diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc
@@ -50,5 +50,48 @@ classpath:/jbang.properties
    wrapper.install.dir = .
 ```
 
+== Proxy configuration
 
+If you use proxies there are a few settings to apply to make JBang *fully* work with proxies.
+
+First the proxy settings for bash/zsh scripting part (needed if jbang nor java is not already installed). This is done by setting the `http_proxy` and `https_proxy` environment variables. For example:
+
+```bash
+http_proxy=http://proxyhost:8888
+https_proxy=http://proxyhost:8888
+```
+
+Second the proxy settings for Java itself. This is done by setting the `JAVA_TOOL_OPTIONS` environment variable. For example:
+
+```bash
+export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=proxyhost -Dhttp.proxyPort=8888 -Dhttps.proxyHost=proxyhost -Dhttps.proxyPort=8888"
+```
+
+Finally JBang uses maven resolver to download dependencies. Maven resolver uses the `settings.xml` file to configure proxies. The `settings.xml` file is usually located in `~/.m2/settings.xml`. For example:
+
+```xml
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
+    <proxies>
+        <!-- For HTTP -->
+        <proxy>
+            <id>http-proxy</id>
+            <active>true</active>
+            <protocol>http</protocol>
+            <host>proxyhost</host>
+            <port>8888</port>
+        </proxy>
+        <!-- For HTTPS -->
+        <proxy>
+            <id>https-proxy</id>
+            <active>true</active>
+            <protocol>https</protocol>
+            <host>proxyhost</host>
+            <port>8888</port>
+        </proxy>
+    </proxies>
+</settings>
+```
 
diff --git a/misc/proxy/README.md b/misc/proxy/README.md
@@ -21,17 +21,18 @@ docker-compose run --rm jbang
 You'll now have access to a shell in a container that can only access
 the Internet via the proxy at the URL `tinyproxy:8888`. Environment
 variables have already been set for Linux itself so `curl` will work
-just fine.
+just fine. Likewise `~/.m2/settings.xml` is setup so that Maven will
+honor the proxy settings too.
 
 Setting the proxy options for Java requires a bit more work and doesn't
 always work. One way is to inherit the settings from the OS, like this:
 
 ```
-JAVA_TOOL_OPTIONS="-Djava.net.useSystemProxies=true"
+export JAVA_TOOL_OPTIONS="-Djava.net.useSystemProxies=true"
 ```
 
 The other option is to set it explicitly:
 
 ```
-JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=tinyproxy -Dhttp.proxyPort=8888 -Dhttps.proxyHost=tinyproxy -Dhttps.proxyPort=8888"
+export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=tinyproxy -Dhttp.proxyPort=8888 -Dhttps.proxyHost=tinyproxy -Dhttps.proxyPort=8888"
 ```
diff --git a/misc/proxy/config/settings.xml b/misc/proxy/config/settings.xml
@@ -0,0 +1,23 @@
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
+    <proxies>
+        <!-- For HTTP -->
+        <proxy>
+            <id>tiny-http-proxy</id>
+            <active>true</active>
+            <protocol>http</protocol>
+            <host>tinyproxy</host>
+            <port>8888</port>
+        </proxy>
+        <!-- For HTTPS -->
+        <proxy>
+            <id>tiny-https-proxy</id>
+            <active>true</active>
+            <protocol>https</protocol>
+            <host>tinyproxy</host>
+            <port>8888</port>
+        </proxy>
+    </proxies>
+</settings>
diff --git a/misc/proxy/docker-compose.yml b/misc/proxy/docker-compose.yml
@@ -8,7 +8,7 @@ services:
       - no-internet
       - internet
     volumes:
-      - ./config:/etc/tinyproxy
+      - ./config/tinyproxy.conf:/etc/tinyproxy/tinyproxy.conf
     restart: unless-stopped
 
   jbang:
@@ -24,6 +24,7 @@ services:
     volumes:
       - ../../build/install/jbang/bin:/jbang/bin:ro
       - ../../itests:/itests:ro
+      - ./config/settings.xml:/root/.m2/settings.xml
     working_dir: /itests
 
 networks: