{"id":15651393,"url":"https://github.com/garutilorenzo/docker-swarm-ingress","last_synced_at":"2025-07-08T16:38:07.206Z","repository":{"id":48350027,"uuid":"413403443","full_name":"garutilorenzo/docker-swarm-ingress","owner":"garutilorenzo","description":"Nginx swarm ingress controller, a minimalistic approach to allow routing into a Docker Swarm based on the public hostnames.","archived":false,"fork":false,"pushed_at":"2024-02-23T09:14:49.000Z","size":42,"stargazers_count":40,"open_issues_count":2,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T07:47:10.326Z","etag":null,"topics":["docker","docker-container","docker-swarm","dockerfile","ingress","ingress-controller","ingress-nginx","nginx","nginx-proxy"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/garutilorenzo/docker-swarm-ingress","language":"Smarty","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/garutilorenzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-10-04T12:03:32.000Z","updated_at":"2025-03-17T00:50:14.000Z","dependencies_parsed_at":"2024-02-23T09:28:07.626Z","dependency_job_id":"1a39e770-b339-48d4-8d10-b51cae87be2a","html_url":"https://github.com/garutilorenzo/docker-swarm-ingress","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garutilorenzo%2Fdocker-swarm-ingress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garutilorenzo%2Fdocker-swarm-ingress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garutilorenzo%2Fdocker-swarm-ingress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garutilorenzo%2Fdocker-swarm-ingress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/garutilorenzo","download_url":"https://codeload.github.com/garutilorenzo/docker-swarm-ingress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251751029,"owners_count":21637842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-container","docker-swarm","dockerfile","ingress","ingress-controller","ingress-nginx","nginx","nginx-proxy"],"created_at":"2024-10-03T12:38:13.800Z","updated_at":"2025-04-30T17:33:22.817Z","avatar_url":"https://github.com/garutilorenzo.png","language":"Smarty","funding_links":[],"categories":["Smarty"],"sub_categories":[],"readme":"# Ingress Service for Docker Swarm\n\n[![docker swarm ingress CI](https://github.com/garutilorenzo/docker-swarm-ingress/actions/workflows/ci.yml/badge.svg)](https://github.com/garutilorenzo/docker-swarm-ingress/actions/workflows/ci.yml)\n[![GitHub issues](https://img.shields.io/github/issues/garutilorenzo/docker-swarm-ingress)](https://github.com/garutilorenzo/docker-swarm-ingress/issues)\n![GitHub](https://img.shields.io/github/license/garutilorenzo/docker-swarm-ingress)\n[![GitHub forks](https://img.shields.io/github/forks/garutilorenzo/docker-swarm-ingress)](https://github.com/garutilorenzo/docker-swarm-ingress/network)\n[![GitHub stars](https://img.shields.io/github/stars/garutilorenzo/docker-swarm-ingress)](https://github.com/garutilorenzo/docker-swarm-ingress/stargazers)\n[![Docker Stars](https://img.shields.io/docker/stars/garutilorenzo/docker-swarm-ingress?style=flat-square)](https://hub.docker.com/r/garutilorenzo/docker-swarm-ingress) [![Docker Pulls](https://img.shields.io/docker/pulls/garutilorenzo/docker-swarm-ingress?style=flat-square)](https://hub.docker.com/r/garutilorenzo/docker-swarm-ingress)\n\n![nginx-ingress-controller-small](https://garutilorenzo.github.io/images/nginx-ingress-controller-small.png)\n\nThis is a minimalistic approach to allow a routing of external requests into a\nDocker Swarm while routing based on the public hostname.\n\nEach service which should be routed has so enable the routing using labels.\n\n\n## The Ingress Service\n\nThe ingress service consists of a nginx server and a python script which periodically\nupdates the nginx configuration. The service communicates with the docker daemon\nto retrieve the latest service configuration.\n\nA detailed guide with some examples is available [here](https://garutilorenzo.github.io/nginx-ingress-controller/)\n\n### Run the Service\n\nThe Ingress service acts as a reverse proxy in your cluster. It exposes port 80\nto the public an redirects all requests to the correct service in background.\nIt is important that the ingress service can reach other services via the Swarm\nnetwork (that means they must share a network).\n\n```\ndocker service create --name ingress \\\n  --network ingress-routing \\\n  -p 80:80 \\\n  -p 443:443 \\\n  --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock \\\n  --constraint node.role==manager \\\n  garutilorenzo/docker-swarm-ingress\n```\n\nIt is important to mount the docker socket, otherwise the service can't update\nthe configuration of nginx.\n\nThe ingress service should be scaled to multiple nodes to prevent short outages\nwhen the node with the ingress servic becomes unresponsive (use `--replicas X` when starting the service).\n\nTo deploy the service you can use the .yml file in the example directory:\n\n```\ndocker stack deploy -c exaples/docker-ingress-stack.yml ingress\n```\n\ncheck the stack status:\n\n```\ndocker stack ps ingress\n\n\nID             NAME                    IMAGE                                    NODE      DESIRED STATE   CURRENT STATE              ERROR     PORTS\ni28vwvmua0b3   ingress_nginx.1   garutilorenzo/docker-swarm-ingress:dev   node-2    Running         Preparing 11 seconds ago\n```\n\ncheck the service logs:\n\n```\ndocker service  logs -f ingress_nginx\n\n\ningress_nginx.1.i28vwvmua0b3@node-2    | Generating a RSA private key\ningress_nginx.1.i28vwvmua0b3@node-2    | ........................................................++++\ningress_nginx.1.i28vwvmua0b3@node-2    | ................................................++++\ningress_nginx.1.i28vwvmua0b3@node-2    | writing new private key to '/etc/nginx/default.key'\ningress_nginx.1.i28vwvmua0b3@node-2    | -----\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: using the \"epoll\" event method\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: nginx/1.21.3\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: built by gcc 10.3.1 20210424 (Alpine 10.3.1_git20210424) \ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: OS: Linux 5.4.0-88-generic\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: start worker processes\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: start worker process 8\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:51:59 [notice] 1#1: start worker process 9\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 10#10: signal process started\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 1#1: signal 1 (SIGHUP) received from 10, reconfiguring\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 1#1: reconfiguring\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 9#9: gracefully shutting down\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 9#9: exiting\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 9#9: exit\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 8#8: gracefully shutting down\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 8#8: exiting\ningress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:52:01 [notice] 8#8: exit\n\n```\n\n### Register a Service for Ingress\n\nA service can easily be configured using ingress. You must simply provide a label\n`ingress.host` which determines the hostname under wich the service should be\npublicly available.\n\n## Configuration Labels\n\nAdditionally to the hostname you can also map another port and path of your service.\nBy default a request would be redirected to `http://service-name:80/`.\n\n| Label   | Required | Default | Description |\n| ------- | -------- | ------- | ----------- |\n| `ingress.host` | `yes` | `-`      | When configured ingress is enabled. The hostname which should be mapped to the service. Wildcards `*` and regular expressions are allowed. |\n| `ingress.port` | `no`  | `80`    | The port which serves the service in the cluster. |\n| `ingress.virtual_proto` | `no`  | `http`     | The protocol used to connect to the backends |\n| `ingress.certificate_name` | `no`  | ``     | Custom name of ssl certificate used instead of domain name |\n\n\n### Run a Service with Enabled Ingress\n\nIt is important to run the service which should be used for ingress that it\nshares a network. A good way to do so is to create a common network `ingress-routing`\n(`docker network create --driver overlay ingress-routing`).\n\nTo start a service with ingress simply pass the required labels on creation.\n\n```\ndocker service create --name my-service \\\n  --network ingress-routing \\\n  --label ingress.host=my-service.company.tld \\\n  nginx\n```\n\nIt is also possible to later add a service to ingress using `service update`.\n\n```\ndocker service update \\\n  --label-add ingress.host=my-service.company.tld \\\n  --label-add ingress.port=8080 \\\n  my-service\n```\n\nYou can also use the example provided in the examples dir for a test:\n\n```\ndocker stack deploy -c examples/example-service.yml service-test\n```\n\nThe service use the *my-service.company.tld* hostname.\n\nWait for nginx reload, check the logs of the nginx service:\n\n```\ndocker service  logs -f ingress_nginx\n\n...\n...\n\nnginx-ingress_nginx.1.i28vwvmua0b3@node-2    | 2021/10/18 13:53:31 [notice] 94#94: signal process started\n```\n\n### SSL\n\nBy default the container is configured in \"SSL Passthrough\" mode. It's also possible to use SSL Termination and SSL Bridging mode.\nSSL Passthrough and SSL Termination/Bridging exclude each others so the nginx ingress controller can work in SSL termination mode **OR** in SSL Termination/Bridging mode.\n\nTo set the mode use the environment variable PROXY_MODE, default ssl-passthrough.\n\nTo set the container in Termination/Bridging set the variable PROXY_MODE to any value not equal to \"ssl-passthrough\" (Example. ssl-term-bridg)\nA complete stack example is available here examples/docker-ingress-stack-ssl_term_bridg.yml\n\nTo use Termination/Bridging mode we need to create the certificates used to expose our site in https, to do this we need to create two secrets for each domain we need to expose.\n\nThe certificates name are very important, for example if our domain is my-service.company.tld the secrets must be named:\n\n* my-service.company.tld.crt\n* my-service.company.tld.key\n\nTo create the secrets you can use this command:\n\n```\ndocker secret create my-service.company.tld.key my-service.key\ndocker secret create my-service.company.tld.crt my-service.crt\n```\n\nWhere my-service.key and  my-service.crt are your ssl key and certificate (self-signed, letsencrypt, purchased and so on..)\n\nThis secrets then must be attached to our ingress container\n\n```\ndocker service create --name ingress \\\n  --network ingress-routing \\\n  -p 80:80 \\\n  -p 443:443 \\\n  --secret my-service.company.tld.crt \\\n  --secret my-service.company.tld.key \\\n  --mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock \\\n  --constraint node.role==manager \\\n  garutilorenzo/docker-swarm-ingress\n```\n\n#### Use custom certificate name\n\nCreate the secrets with a custom name in this case is `wildcard-name.tld`:\n\n```\ndocker secret create wildcard-name.tld.key my-service.key\ndocker secret create wildcard-name.tld.crt my-service.crt\n```\n\nthen use the label `ingress.certificate_name` to specify the custom certificate name:\n\n```\ndocker service create --name my-service \\\n  --network ingress-routing \\\n  --label ingress.host=my-service.company.tld \\\n  --label ingress.certificate_name=wildcard-name.tld \\\n  nginx\n```\n\n#### SSL Passthrough\n\nIt's possible to enable SSL Passthrough using the following labels:\n\n* --label-add ingress.ssl=enable\n* --label-add ingress.ssl_redirect=enable\n\nwith the ingress.ssl=enable we enalble the SSL Passthrough to our backend:\n\nClient --\u003e Nginx-Ingress (No SSL) --\u003e Backend (SSL)\n\nwith ingress.ssl_redirect=enable nignx redirect all http traffic to https.\nFor a detailed example see examples/example-ssl-service.yml\n\n#### SSL Termination\n\nTo use SSL termination mode on our backend container we need to add the following labels:\n\n* --label-add ingress.ssl=enable\n* --label-add ingress.ssl_redirect=enable\n* --label-add ingress.virtual_proto=http\n* --label-add ingress.port=80\n\nClient --\u003e Nginx-Ingress (SSL) --\u003e Backend (No SSL)\nFor a detailed example see examples/example-service-ssl-termination.yml\n\n#### SSL Bridging\n\nTo use SSL bridging mode on our backend container we need to add the following labels:\n\n* --label-add ingress.ssl=enable\n* --label-add ingress.ssl_redirect=enable\n* --label-add ingress.virtual_proto=https\n* --label-add ingress.port=443\n\nClient --\u003e Nginx-Ingress (SSL) --\u003e Backend (SSL)\nFor a detailed example see examples/example-service-ssl-bridging.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarutilorenzo%2Fdocker-swarm-ingress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgarutilorenzo%2Fdocker-swarm-ingress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarutilorenzo%2Fdocker-swarm-ingress/lists"}