2023-07-13 10:52:17 +02:00
3 changed files with 79 additions and 57 deletions
--- a/.vscode/dictionaries/project-words.txt
+++ b/.vscode/dictionaries/project-words.txt
@ -1,10 +1,14 @@
+FOSS
+gitea
 Gitea
 LOGLEVEL
 MAXCLIENTS
+ocram
 Quickstart
 swarmproxy
 Swarmproxy
 tbd
+tinyproxy
 Tinyproxy
 TINYPROXY
 UID
--- a/README.md
+++ b/README.md
@ -16,12 +16,10 @@
 🦁 Swarmproxy is a simple http proxy to limit your outbound traffic.
 </p>

-## ❓ FAQ
-
-### What ist Swarmproxy?
+## 📖 About

 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.
- Upstream proxy with or without authentication
- Optional domain based whitelist filter.
+- ✔️ Prevent direct web access from Container workload.
+- ✔️ Upstream proxy with or without authentication
+- ✔️ 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
-> does not customize your iptables or so
+- ☣️ Swarmproxy does not block the web access or other traffic if you workload doesn't use a proxy
+- ☣️ 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
-    configs:
-      - source: filter_file
-        target: /app/filter
+      # - ./filter.txt:/app/filter:ro
+    #configs:
+    #  - source: filter_file
+    #    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/ajoergensen/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.

 ## ⚖️ License (AGPLv3)

--- a/docker-compose.yml
+++ b/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
-
-#configs:
-#  filter_file:
-#    # config can be predefined / external or loaded from file
-#    #external: true
-#    file: ./filter.txt
-
-#secrets:
-#  upstream-proxy:
-#    external: true
+  dmz:
+    attachable: true
+  backend:
+    internal: 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=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
+      - LOGLEVEL=Info
    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