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