add full Swarmproxy example

.vscode/dictionaries/project-words.txt

@@ -1,10 +1,14 @@
+FOSS
+gitea
 Gitea
 LOGLEVEL
 MAXCLIENTS
+ocram
 Quickstart
 swarmproxy
 Swarmproxy
 tbd
+tinyproxy
 Tinyproxy
 TINYPROXY
 UID

README.md

@@ -16,12 +16,10 @@
 🦁 Swarmproxy is a simple http proxy to limit your outbound traffic.
 </p>
 
-## ❓ FAQ
+## 📖 About
-
-### What ist Swarmproxy?
 
 Swarmproxy is a simply way to integrate a http proxy in your Docker swarm cluster or any other container network.
-It acts as an centralized proxy to limit your outbound / egress traffic. You can also enable a whitelist filter to
+It acts as an centralized proxy to limit your outbound / egress traffic. You can also add a whitelist filter to
 limit the allowed domains. There is also an option to use a upstream proxy.
 
 ### What does Swarmproxy for you?
@@ -31,16 +29,18 @@ Therefore, unfiltered Internet access may be prohibited.
 
 So Swarmproxy could help you with these features:
 
-- Prevent direct web access from Container workload.
+- ✔️ Prevent direct web access from Container workload.
-- Upstream proxy with or without authentication
+- ✔️ Upstream proxy with or without authentication
-- Optional domain based whitelist filter.
+- ✔️ Optional domain based whitelist filter.
 
 ### What does Swarmproxy not?
 
 Swarmproxy is just a supercharged Tinyproxy where you can point your container workload to.
 
-> ☣️ Swarmproxy does not block the web access or other traffic if the proxy is not used. It's not a firewall, and it
+- ☣️ Swarmproxy does not block the web access or other traffic if you workload doesn't use a proxy
-> does not customize your iptables or so
+- ☣️ It's not a firewall, thus it does not customize your iptables or any other firewall policies.
+
+## 🚀 Quickstart
 
 ### 1. ⚡ Get the image 📦
 
@@ -49,10 +49,13 @@ You can download the image from the Gitea embedded container registry: `gitea.oc
 - `latest`, `main` - Is based on the lasted master branch commit.
 - `1`, `0.1`, `0.1.0` - tag based version.
 
-> **💡 NOTE: See the [packages page](https://gitea.ocram85.com/OCram85/-/packages/container/swarmproxy/latest) for latest version and all other available tags.**
+> **💡 NOTE: See the [packages page](https://gitea.ocram85.com/OCram85/-/packages/container/swarmproxy/latest)
+> for latest version and all other available tags.**
 
 ### 2. 🛡️ Run as Docker Swarm Stack
 
+This example shows all available configuration keys / environment variables for Swarmproxy.
+
 ```yaml
 version: "3.8"
 
@@ -80,6 +83,7 @@ services:
     #secrets:
     #  - upstream-proxy
     environment:
+      - LOGLEVEL=Info
       # Recommended settings
       # Use an optional upstream proxy
       #- UPSTREAM_PROXY=
@@ -92,16 +96,15 @@ services:
       #- TINYPROXY_GID=5123
       #- PORT=8888
       #- TIMEOUT=600
-      #- LOGLEVEL=Info
       #- MAXCLIENTS=600
       #- FILTER_FILE=/app/filter
     volumes:
       # You can mount a single filter file into the container.
       # To reload the file use the docker kill -s USR1 <container_id| container_name> command.
-      - ./filter.txt:/app/filter:ro
+      # - ./filter.txt:/app/filter:ro
-    configs:
+    #configs:
-      - source: filter_file
+    #  - source: filter_file
-        target: /app/filter
+    #    target: /app/filter
     networks:
       egress:
         aliases:
@@ -109,7 +112,10 @@ services:
           - proxy
 ```
 
-### 3. Use the proxy form other containers
+### 3. 🚀 Full example
+
+You can find a full example containing a fake upstream, swarmproxy and workload container in the
+[docker-compose.yml](docker-compose.yml) file.
 
 
 ## 💣 Known Issues
@@ -139,11 +145,11 @@ code in Copilot.
 
 ## 🙏 Credits
 
-swarmproxy is based on the following projects and wouldn't be possible without them:
+Swarmproxy is based on the following projects and wouldn't be possible without them:
 
 - [Tinyproxy](https://github.com/tinyproxy/tinyproxy) - The Tinyproxy project itself
-- [docker-tinyproxy](https://github.com/kalaksi/docker-tinyproxy) - A containerized tinyproxy variant.
+- [docker-tinyproxy](https://github.com/kalaksi/docker-tinyproxy) - A containerized Tinyproxy variant.
-- [docker-tinyproxy](https://github.com/ajoergensen/docker-tinyproxy) - A containerized tinyproxy variant.
+- [docker-tinyproxy](https://github.com/ajoergensen/docker-tinyproxy) - A containerized Tinyproxy variant.
 
 ## ⚖️ License (AGPLv3)
 

docker-compose.yml

@@ -1,54 +1,66 @@
 version: "3.8"
 
+
+# Setting up 3 default networks to act as dummy:
+# - backend : internal only network
+# - dmz : dmz network with connections allowed from internal and external
+# - egress : dummy egress zone with fake upstream proxy
+
 networks:
   egress:
    attachable: true
-   #external: true
+  dmz:
-
+    attachable: true
-#configs:
+  backend:
-#  filter_file:
+    internal: true
-#    # config can be predefined / external or loaded from file
-#    #external: true
-#    file: ./filter.txt
-
-#secrets:
-#  upstream-proxy:
-#    external: true
 
 services:
-  swarmproxy:
+  # Creating a fake upstream proxy
+  upstream:
     image: gitea.ocram85.com/ocram85/swarmproxy:latest
     deploy:
       replicas: 1
-    #secrets:
-    #  - upstream-proxy
     environment:
-      # Recommended settings
+      - LOGLEVEL=Info
-      - LOGLEVEL=Connect
-
-      # Use an optional upstream proxy
-      #- UPSTREAM_PROXY=
-      # Set UPSTREAM_PROXY as docker secret if your upstream needs authentication
-      # Eg.: http://user:password@upstream.intra:3128
-      #- UPSTREAM_PROXY_FILE=/run/secrets/UPSTREAM_PROXY
-
-      # OPTIONAL config keys
-      #- TINYPROXY_UID=5123
-      #- TINYPROXY_GID=5123
-      #- PORT=8888
-      #- TIMEOUT=600
-      #- MAXCLIENTS=600
-      #- FILTER_FILE=/app/filter
-    # You can mount a single filter file into the container.
-    # To reload the file use the docker kill -s USR1 <container_id| container_name> command.
-    #volumes:
-    #  - ./filter.txt:/app/filter:ro
-    # alenate filter file mount
-    #configs:
-    #  - source: filter_file
-    #    target: /app/filter
     networks:
       egress:
+        aliases:
+          - upstream
+
+  # Creating our swarmproxy instance to use the external upstream proxy
+  swarmproxy:
+    # Do not use the `latest` tag in production!
+    image: gitea.ocram85.com/ocram85/swarmproxy:latest
+    depends_on:
+      - upstream
+    deploy:
+      replicas: 1
+    environment:
+      - UPSTREAM_PROXY=upstream:8888
+      - LOGLEVEL=Info
+    networks:
+      dmz:
         aliases:
           - swarmproxy
           - proxy
+      egress:
+
+  # container workload example whicht tries to communicate through our swarmproxy instance
+  # http request / response:
+  # [curl container] <---|req/res|---> [swarmproxy] <---|req/res|---> [upstream] <---|req/res|---> [target]
+  curl:
+    image: curlimages/curl:8.1.2
+    command: ["-I", "-x", "proxy:8888", "https://google.com"]
+    depends_on:
+      - upstream
+      - swarmproxy
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: any
+        delay: 10s
+        max_attempts: 5
+        window: 120s
+    networks:
+      - backend
+      - dmz