From f790b9aa546ba449218a929d3fcac5df3875bf53 Mon Sep 17 00:00:00 2001
From: Robert Baker <51850403+robertbaker@users.noreply.github.com>
Date: Mon, 28 Oct 2019 07:50:06 -0700
Subject: [PATCH] Add example for changing the port used by traefik to connect
 to a service

---
 docs/content/routing/providers/docker.md      | 187 ++++++++++--------
 .../routing/services/.markdownlint.json       |   3 +-
 docs/content/routing/services/index.md        |  64 +++---
 3 files changed, 139 insertions(+), 115 deletions(-)

diff --git a/docs/content/routing/providers/docker.md b/docs/content/routing/providers/docker.md
index 9fc796b87..f81d0daaa 100644
--- a/docs/content/routing/providers/docker.md
+++ b/docs/content/routing/providers/docker.md
@@ -12,16 +12,16 @@ Attach labels to your containers and let Traefik do the rest!
 ??? example "Configuring Docker & Deploying / Exposing Services"
 
     Enabling the docker provider
-    
+
     ```toml tab="File (TOML)"
     [providers.docker]
     ```
-    
+
     ```yaml tab="File (YAML)"
     providers:
       docker: {}
     ```
-    
+
     ```bash tab="CLI"
     --providers.docker=true
     ```
@@ -37,6 +37,27 @@ Attach labels to your containers and let Traefik do the rest!
           - traefik.http.routers.my-container.rule=Host(`mydomain.com`)
     ```
 
+??? example "Specify a Custom Port for the Container"
+
+    Forward requests for `http://mydomain.com` to `http://<private IP of container>:12345`:
+
+    ```yaml
+    version: "3"
+    services:
+      my-container:
+        # ...
+        labels:
+          - traefik.http.routers.my-container.rule=Host(`mydomain.com`)
+          # Tell Traefik to use the port 12345 to connect to `my-container`
+          - traefik.http.services.my-service.loadbalancer.server.port=12345
+    ```
+
+    !!! important "Traefik Connecting to the Wrong Port: `HTTP/502 Gateway Error`"
+        By default, Traefik uses the first exposed port of a container.
+
+        Setting the label `raefik.http.services.xxx.loadbalancer.server.port`
+        overrides that behavior.
+
 ??? example "Configuring Docker Swarm & Deploying / Exposing Services"
 
     Enabling the docker provider (Swarm Mode)
@@ -49,7 +70,7 @@ Attach labels to your containers and let Traefik do the rest!
       endpoint = "tcp://127.0.0.1:2377"
       swarmMode = true
     ```
-    
+
     ```yaml tab="File (YAML)"
     providers:
       docker:
@@ -59,7 +80,7 @@ Attach labels to your containers and let Traefik do the rest!
         endpoint: "tcp://127.0.0.1:2375"
         swarmMode: true
     ```
-    
+
     ```bash tab="CLI"
     --providers.docker.endpoint="tcp://127.0.0.1:2375"
     --providers.docker.swarmMode=true
@@ -85,7 +106,7 @@ Attach labels to your containers and let Traefik do the rest!
 ## Routing Configuration
 
 !!! info "Labels"
-    
+
     - Labels are case insensitive.
     - The complete list of labels can be found in [the reference page](../../reference/dynamic-configuration/docker.md).
 
@@ -132,81 +153,81 @@ For example, to change the rule, you could add the label ```traefik.http.routers
 !!! warning "The character `@` is not authorized in the router name `<router_name>`."
 
 ??? info "`traefik.http.routers.<router_name>.rule`"
-    
-    See [rule](../routers/index.md#rule) for more information. 
-    
+
+    See [rule](../routers/index.md#rule) for more information.
+
     ```yaml
     - "traefik.http.routers.myrouter.rule=Host(`mydomain.com`)"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.entrypoints`"
-    
-    See [entry points](../routers/index.md#entrypoints) for more information. 
-    
+
+    See [entry points](../routers/index.md#entrypoints) for more information.
+
     ```yaml
     - "traefik.http.routers.myrouter.entrypoints=web,websecure"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.middlewares`"
-    
-    See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information. 
-    
+
+    See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information.
+
     ```yaml
     - "traefik.http.routers.myrouter.middlewares=auth,prefix,cb"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.service`"
-    
-    See [rule](../routers/index.md#service) for more information. 
-    
+
+    See [rule](../routers/index.md#service) for more information.
+
     ```yaml
     - "traefik.http.routers.myrouter.service=myservice"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.tls`"
-    
+
     See [tls](../routers/index.md#tls) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.tls=true"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.tls.certresolver`"
-    
+
     See [certResolver](../routers/index.md#certresolver) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.tls.certresolver=myresolver"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.tls.domains[n].main`"
-    
+
     See [domains](../routers/index.md#domains) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.tls.domains[0].main=foobar.com"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.tls.domains[n].sans`"
-    
+
     See [domains](../routers/index.md#domains) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.tls.options`"
-    
+
     See [options](../routers/index.md#options) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.tls.options=foobar"
     ```
 
 ??? info "`traefik.http.routers.<router_name>.priority`"
-    
+
     See [options](../routers/index.md#priority) for more information.
-    
+
     ```yaml
     - "traefik.http.routers.myrouter.priority=42"
     ```
@@ -222,124 +243,124 @@ you'd add the label `traefik.http.services.<name-of-your-choice>.loadbalancer.pa
 !!! warning "The character `@` is not authorized in the service name `<service_name>`."
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.server.port`"
-    
+
     Registers a port.
     Useful when the container exposes multiples ports.
-    
+
     Mandatory for Docker Swarm.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.server.port=8080"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.server.scheme`"
-    
+
     Overrides the default scheme.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.server.scheme=http"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.passhostheader`"
-    
+
     See [pass Host header](../services/index.md#pass-host-header) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.passhostheader=true"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=foobar.com"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.interval`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.path`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.port`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.port=42"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout`"
-    
+
     See [health check](../services/index.md#health-check) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky`"
-    
+
     See [sticky sessions](../services/index.md#sticky-sessions) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.sticky=true"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly`"
-    
+
     See [sticky sessions](../services/index.md#sticky-sessions) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name`"
-    
+
     See [sticky sessions](../services/index.md#sticky-sessions) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure`"
-    
+
     See [sticky sessions](../services/index.md#sticky-sessions) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true"
     ```
 
 ??? info "`traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval`"
-    
+
     See [response forwarding](../services/index.md#response-forwarding) for more information.
-    
+
     ```yaml
     - "traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10"
     ```
@@ -397,73 +418,73 @@ You can declare TCP Routers and/or Services using labels.
 #### TCP Routers
 
 ??? info "`traefik.tcp.routers.<router_name>.entrypoints`"
-    
+
     See [entry points](../routers/index.md#entrypoints_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.rule`"
-    
+
     See [rule](../routers/index.md#rule_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.rule=HostSNI(`myhost.com`)"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.service`"
-    
+
     See [service](../routers/index.md#services) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.service=myservice"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls`"
-    
+
     See [TLS](../routers/index.md#tls_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls=true"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls.certresolver`"
-    
+
     See [certResolver](../routers/index.md#certresolver_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].main`"
-    
+
     See [domains](../routers/index.md#domains_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls.domains[0].main=foobar.com"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].sans`"
-    
+
     See [domains](../routers/index.md#domains_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls.options`"
-    
+
     See [options](../routers/index.md#options_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls.options=mysoptions"
     ```
 
 ??? info "`traefik.tcp.routers.<router_name>.tls.passthrough`"
-    
+
     See [TLS](../routers/index.md#tls_1) for more information.
-    
+
     ```yaml
     - "traefik.tcp.routers.mytcprouter.tls.passthrough=true"
     ```
@@ -471,17 +492,17 @@ You can declare TCP Routers and/or Services using labels.
 #### TCP Services
 
 ??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.port`"
-    
+
     Registers a port of the application.
-    
+
     ```yaml
     - "traefik.tcp.services.mytcpservice.loadbalancer.server.port=423"
     ```
 
 ??? info "`traefik.tcp.services.<service_name>.loadbalancer.terminationdelay`"
-        
+
     See [termination delay](../services/index.md#termination-delay) for more information.
-    
+
     ```yaml
     - "traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100"
     ```
diff --git a/docs/content/routing/services/.markdownlint.json b/docs/content/routing/services/.markdownlint.json
index e803880c0..dd98ee65a 100644
--- a/docs/content/routing/services/.markdownlint.json
+++ b/docs/content/routing/services/.markdownlint.json
@@ -1,4 +1,5 @@
 {
     "extends": "../../../.markdownlint.json",
-    "MD024": false
+    "MD024": false,
+    "MD046": false
 }
diff --git a/docs/content/routing/services/index.md b/docs/content/routing/services/index.md
index 212754fe0..0b582918d 100644
--- a/docs/content/routing/services/index.md
+++ b/docs/content/routing/services/index.md
@@ -5,9 +5,9 @@ Configuring How to Reach the Services
 
 ![services](../../assets/img/services.png)
 
-The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests. 
+The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests.
 
-## Configuration Example
+## Configuration Examples
 
 ??? example "Declaring an HTTP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
 
@@ -17,11 +17,11 @@ The `Services` are responsible for configuring how to reach the actual services
       [http.services.my-service.loadBalancer]
 
         [[http.services.my-service.loadBalancer.servers]]
-          url = "http://private-ip-server-1/"
+          url = "http://<private-ip-server-1>:<private-port-server-1>/"
         [[http.services.my-service.loadBalancer.servers]]
-          url = "http://private-ip-server-2/"
+          url = "http://<private-ip-server-2>:<private-port-server-2>/"
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -29,8 +29,8 @@ The `Services` are responsible for configuring how to reach the actual services
         my-service:
           loadBalancer:
             servers:
-            - url: "http://private-ip-server-1/"
-            - url: "http://private-ip-server-2/"
+            - url: "http://<private-ip-server-1>:<private-port-server-1>/"
+            - url: "http://<private-ip-server-2>:<private-port-server-2>/"
     ```
 
 ??? example "Declaring a TCP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
@@ -40,26 +40,28 @@ The `Services` are responsible for configuring how to reach the actual services
     [tcp.services]
       [tcp.services.my-service.loadBalancer]
          [[tcp.services.my-service.loadBalancer.servers]]
-           address = "xx.xx.xx.xx:xx"
+           address = "<private-ip-server-1>:<private-port-server-1>"
          [[tcp.services.my-service.loadBalancer.servers]]
-           address = "xx.xx.xx.xx:xx"
+           address = "<private-ip-server-2>:<private-port-server-2>"
     ```
-    
+
     ```yaml tab="YAML"
     tcp:
       services:
         my-service:
-          loadBalancer:         
+          loadBalancer:
             servers:
-            - address: "xx.xx.xx.xx:xx"
-            - address: "xx.xx.xx.xx:xx"
+            - address: "<private-ip-server-1>:<private-port-server-1>"
+            - address: "<private-ip-server-2>:<private-port-server-2>"
     ```
 
 ## Configuring HTTP Services
 
 ### Servers Load Balancer
 
-The load balancers are able to load balance the requests between multiple instances of your programs. 
+The load balancers are able to load balance the requests between multiple instances of your programs.
+
+Each service has a load-balancer, even if there is only one server to forward traffic to.
 
 ??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../../providers/file.md)"
 
@@ -87,10 +89,10 @@ The load balancers are able to load balance the requests between multiple instan
 #### Servers
 
 Servers declare a single instance of your program.
-The `url` option point to a specific instance. 
+The `url` option point to a specific instance.
 
 !!! info ""
-    Paths in the servers' `url` have no effect. 
+    Paths in the servers' `url` have no effect.
     If you want the requests to be sent to a specific path on your servers,
     configure your [`routers`](../routers/index.md) to use a corresponding [middleware](../../middlewares/overview.md) (e.g. the [AddPrefix](../../middlewares/addprefix.md) or [ReplacePath](../../middlewares/replacepath.md)) middlewares.
 
@@ -103,7 +105,7 @@ The `url` option point to a specific instance.
         [[http.services.my-service.loadBalancer.servers]]
           url = "http://private-ip-server-1/"
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -142,21 +144,21 @@ For now, only round robin load balancing is supported:
     ```
 
 #### Sticky sessions
-  
+
 When sticky sessions are enabled, a cookie is set on the initial request to track which server handles the first response.
 On subsequent requests, the client is forwarded to the same server.
 
 !!! info "Stickiness & Unhealthy Servers"
-   
+
     If the server specified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).
 
-!!! info "Cookie Name" 
-    
+!!! info "Cookie Name"
+
     The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`).
 
 !!! info "Secure & HTTPOnly flags"
 
-    By default, the affinity cookie is created without those flags. One however can change that through configuration. 
+    By default, the affinity cookie is created without those flags. One however can change that through configuration.
 
 ??? example "Adding Stickiness -- Using the [File Provider](../../providers/file.md)"
 
@@ -166,7 +168,7 @@ On subsequent requests, the client is forwarded to the same server.
       [http.services.my-service]
         [http.services.my-service.loadBalancer.sticky.cookie]
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -223,8 +225,8 @@ Below are the available options for the health check mechanism:
     The interval must be greater than the timeout. If configuration doesn't reflect this, the interval will be set to timeout + 1 second.
 
 !!! info "Recovering Servers"
-   
-    Traefik keeps monitoring the health of unhealthy servers. 
+
+    Traefik keeps monitoring the health of unhealthy servers.
     If a server has recovered (returning `2xx` -> `3xx` responses again), it will be added back to the load balacer rotation pool.
 
 ??? example "Custom Interval & Timeout -- Using the [File Provider](../../providers/file.md)"
@@ -261,7 +263,7 @@ Below are the available options for the health check mechanism:
           path = "/health"
           port = 8080
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -283,7 +285,7 @@ Below are the available options for the health check mechanism:
           path = "/health"
           scheme = "http"
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -308,7 +310,7 @@ Below are the available options for the health check mechanism:
             My-Custom-Header = "foo"
             My-Header = "bar"
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -337,7 +339,7 @@ By default, `passHostHeader` is true.
         [http.services.Service01.loadBalancer]
           passHostHeader = false
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http:
@@ -358,7 +360,7 @@ Below are the available options for the Response Forwarding mechanism:
   A negative value means to flush immediately after each write to the client.
   The FlushInterval is ignored when ReverseProxy recognizes a response as a streaming response;
   for such responses, writes are flushed to the client immediately.
-  
+
 ??? example "Using a custom FlushInterval -- Using the [File Provider](../../providers/file.md)"
 
     ```toml tab="TOML"
@@ -368,7 +370,7 @@ Below are the available options for the Response Forwarding mechanism:
         [http.services.Service-1.loadBalancer.responseForwarding]
           flushInterval = "1s"
     ```
-    
+
     ```yaml tab="YAML"
     ## Dynamic configuration
     http: