Improve examples

# Conflicts:
#	README.md

.forgejo/workflows/build.yml

@@ -0,0 +1,73 @@
+name: Build and Publish Debian Package
+
+#on: [push]
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  DISTRIBUTION: bookworm
+  COMPONENT: main
+
+jobs:
+  build:
+    runs-on: docker
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # - name: Debug file structure
+      #   run: ls -R
+
+      # - name: Debug pwd
+      #   run: pwd
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+
+      - name: Install FPM dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ruby ruby-dev build-essential
+          sudo gem install --no-document fpm
+
+      - name: Prepare package structure
+        run: |
+          # Create temporary packaging directory
+          mkdir -p package/usr/local/bin
+          mkdir -p package/etc/systemd/system
+          # Copy magicfw.py as the executable and rename if needed
+          cp src/magicfw.py package/usr/local/bin/magicfw
+          chmod +x package/usr/local/bin/magicfw
+          # Copy the systemd service file
+          cp systemd/magicfw.service package/etc/systemd/system/
+
+      - name: Generate version number
+        run: |
+          VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Build Debian package with FPM
+        run: |
+          # The -s dir option tells FPM the source is a directory.
+          # The -t deb option builds a deb package.
+          # -n is the package name and -v the version.
+          fpm -s dir -t deb -n magicfw-docker -v $VERSION -C package \
+              -d "python3" \
+              -d "python3-docker"
+
+      - name: Upload to Forgejo Debian Registry
+        env:
+          FORGEJO_TOKEN: ${{ secrets.FORGEJO_TOKEN }}
+        run: |
+          PACKAGE_NAME="magicfw-docker_${VERSION}_amd64.deb"  # Update version accordingly
+
+          curl --user "your_username:$FORGEJO_TOKEN" \
+               --upload-file ./${PACKAGE_NAME} \
+               "https://git.marcorealacci.me/api/packages/${{ github.repository_owner }}/debian/pool/${{env.DISTRIBUTION}}/${{env.COMPONENT}}/upload"

README.md

@@ -1,4 +1,4 @@
-# Docker Magic Firewall Service: README.md
+# Docker Magic Firewall Service
 
 ## Project Overview
 
@@ -20,14 +20,19 @@ You can define rules per container using specific Docker labels:
 | **Label Key**                          | **Description**                                                                                                                               | **Default** |
 |----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|-------------|
 | `magicfw.firewall.allow_icc`           | Enables communication between the container and other containers on different Docker networks (not normally possible in Docker environments). | `false`     |
-| `magicfw.firewall.allow_external`      | Enables access to external networks (e.g., the internet) for the container.                                                                   | `false`     |
+| `magicfw.firewall.allow_external`      | Enables access from external networks (e.g., the internet) for the container.                                                                   | `false`     |
 
 ### Behavior and Functionalities
 - **Allow ICC (Inter-Container Communication):** When `magicfw.firewall.allow_icc` is `true`, the container can communicate with other containers across **different Docker networks** (useful for applications like reverse proxies such as Traefik). If `false`, the container is isolated from other Docker networks (default Docker behavior).
-- **External Traffic:** When `magicfw.firewall.allow_external` is `true`, the container's network rules allow communication with external IPs.
+- **External Traffic:** When `magicfw.firewall.allow_external` is `true`, the container's network rules allow communication from external networks (useful when NAT is disabled).
 - **Automatic Rule Cleanup:** When a container is restarted, stopped, or removed, the corresponding firewall rules are automatically cleaned.
 - **Support for Published Ports:** Rules are auto-generated for any published ports, restricting incoming traffic to only the ports explicitly exposed via Docker.
 
+## Install
+To make the installation easy, I provide a package for Debian-based distros, follow the instructions here: [https://git.marcorealacci.me/marcorealacci/-/packages/debian/magicfw-docker](https://git.marcorealacci.me/marcorealacci/-/packages/debian/magicfw-docker)
+
+To install the script manually, the required dependencies are `python3` and the `docker` library available from PyPI (`pip3 install docker`).
+
 ## Configuration
 
 ### Environment Variables
@@ -56,13 +61,11 @@ services:
     labels:
       magicfw.firewall.allow_icc: "true"
       magicfw.firewall.allow_external: "true"
-    ports:
-      - 8080:80
 ```
 
 In the above example:
 - The `web` container can communicate with other containers on different Docker networks (`magicfw.firewall.allow_icc: true`).
-- The container can be accessed by external hosts using the container's IP (`magicfw.firewall.allow_external: true`).
+- The container can be accessed by external hosts using the container's IP (**not host IP!**) (`magicfw.firewall.allow_external: true`). This requires a route on other hosts or the router.
 
 #### Example 2
 ```yaml
@@ -92,7 +95,7 @@ services:
 
 In the above example:
 - The `web` container can communicate with other containers on different Docker networks (`magicfw.firewall.allow_icc: true`).
-- External hosts can access the container via both <container IP>:80 and <host IP>:8080 (port mapping still works even with DISABLE_NAT)
+- External hosts can access the container via both <container IP>:80 and <host IP>:8080 (port mapping still works even with `DISABLE_NAT` set to `true`, as only Source NAT will be disabled)
 - External hosts will not be able to access the container on ports other than 80
 
 ---

src/magicfw.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 import os
 import json
 import logging

systemd/magicfw.service

@@ -10,7 +10,7 @@ StartLimitBurst=10
 Type=exec
 Restart=on-failure
 RestartSec=5s
-ExecStart=/usr/bin/python3 /opt/docker_magicfw.py
+ExecStart=/usr/local/bin/magicfw
 
 # Environment variables (customize as needed)
 Environment=LOG_LEVEL=INFO