From 2c63a3a6fb3c6ea8b613f30374c8312f3e4583bb Mon Sep 17 00:00:00 2001 From: OCram85 Date: Thu, 13 Jul 2023 10:52:17 +0200 Subject: [PATCH] add full Swarmproxy example (#12) #### :book: Summary - adds docker-compose.yml full stack example - fix typos #### :bookmark_tabs: Test Plan > :bulb: Select your test plan for the code changes. - [x] CI pipeline tests - [ ] Custom test - [ ] No test plan ##### Details / Justification #### :books: Additional Notes Co-authored-by: OCram85 Reviewed-on: https://gitea.ocram85.com/OCram85/swarmproxy/pulls/12 --- .vscode/dictionaries/project-words.txt | 4 ++ CHANGELOG.md | 3 +- README.md | 44 +++++++------ docker-compose.yml | 88 +++++++++++++++----------- 4 files changed, 81 insertions(+), 58 deletions(-) diff --git a/.vscode/dictionaries/project-words.txt b/.vscode/dictionaries/project-words.txt index 8397afe..2ba4f30 100644 --- 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index a70b14d..c19baf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## [v0.1.0](https://gitea.ocram85.com/OCram85/swarmproxy/releases/tag/v0.1.0) - 2023-07-12 +## [v0.1.0](https://gitea.ocram85.com/OCram85/swarmproxy/releases/tag/v0.1.0) - 2023-07-13 * ✨ FEATURES * Adds entrypoint (#6) @@ -11,4 +11,5 @@ * Use absolute urls for action calls (#10) * Adds renovate support (#8) * ⚙️ META + * Add Readme content (#11) * Adds initial readme (#4) diff --git a/README.md b/README.md index 483f703..416567a 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,10 @@ 🦁 Swarmproxy is a simple http proxy to limit your outbound traffic.

-## ❓ 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 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) diff --git a/docker-compose.yml b/docker-compose.yml index 4634b12..135cab2 100644 --- 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 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