fix: emit Networks and Addresses in deterministic order (#431, #169)

The per-container Networks and Addresses slices passed to templates were
built by ranging over Go maps (NetworkSettings.Networks, NetworkSettings.Ports
and Config.ExposedPorts), whose iteration order is random. This caused
generated files to churn on every regeneration and triggered spurious reloads
/ container restarts even when nothing meaningful changed (#431), and made
`index .Networks 0` pick an arbitrary network (#169).

- internal/context/address.go: sort addresses in GetContainerAddresses via a
  new sortAddresses helper (Port numeric -> Proto -> HostPort -> HostIP -> IP).
- internal/generator/generator.go: sort runtimeContainer.Networks by Name via
  a new sortNetworks helper, right after the network map is collected.
- Tests: add order-sensitive TestSortAddresses / TestGetContainerAddressesSorted
  and TestSortNetworks. Existing order-insensitive address tests still pass.
- README.md: document the deterministic ordering, the behavior change to
  `index .Networks 0`, and how to select a network by name with `where`.

#169 needs no further code change: a specific network is selectable via
`index (where $value.Networks "Name" $name) 0` once the order is stable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: JamBalaya56562

README.md

@@ -394,6 +394,20 @@ For example, this is a JSON version of an emitted RuntimeContainer struct:
 }
 ```
 
+#### Ordering of `Addresses` and `Networks`
+
+The `Addresses` and `Networks` slices are emitted in a deterministic order, so generated output is stable across regenerations and does not trigger spurious reloads/restarts when nothing meaningful changed:
+
+- `Addresses` are sorted by port (compared numerically), then by protocol, host port, host IP and IP.
+- `Networks` are sorted alphabetically by `Name`.
+
+As a consequence, `index .Networks 0` returns the alphabetically-first network (for example `bridge`) rather than an arbitrary one. To select a specific network by name, filter with `where`:
+
+```
+{{ $net := index (where $value.Networks "Name" "my-network") 0 }}
+server {{ $net.IP }}:{{ (index $value.Addresses 0).Port }};
+```
+
 #### Functions
 
 - [Functions from Go](https://pkg.go.dev/text/template#hdr-Functions)

internal/context/address.go

@@ -1,6 +1,9 @@
 package context
 
 import (
+	"sort"
+	"strconv"
+
 	docker "github.com/fsouza/go-dockerclient"
 )
 
@@ -46,5 +49,35 @@ func GetContainerAddresses(container *docker.Container) []Address {
 		}
 	}
 
+	// The addresses above are collected by ranging over Go maps
+	// (NetworkSettings.Ports / Config.ExposedPorts), whose iteration order is
+	// random. Sort them into a deterministic order so the generated output is
+	// stable across regenerations and does not churn (issue #431).
+	sortAddresses(addresses)
+
 	return addresses
 }
+
+// sortAddresses sorts addresses in place into a deterministic, total order:
+// Port (numeric) -> Proto -> HostPort -> HostIP -> IP. (Port, Proto) is already
+// unique among the generated rows; the remaining keys guarantee a total order.
+func sortAddresses(addresses []Address) {
+	sort.Slice(addresses, func(i, j int) bool {
+		a, b := addresses[i], addresses[j]
+		pa, _ := strconv.Atoi(a.Port) // non-numeric / "" -> 0; docker ports are always numeric
+		pb, _ := strconv.Atoi(b.Port)
+		if pa != pb {
+			return pa < pb
+		}
+		if a.Proto != b.Proto {
+			return a.Proto < b.Proto
+		}
+		if a.HostPort != b.HostPort {
+			return a.HostPort < b.HostPort
+		}
+		if a.HostIP != b.HostIP {
+			return a.HostIP < b.HostIP
+		}
+		return a.IP < b.IP
+	})
+}

internal/context/address_test.go

@@ -114,3 +114,50 @@ func TestGenerateContainerAddressesWithNoPorts(t *testing.T) {
 		HostPort:     "",
 	})
 }
+
+func TestSortAddresses(t *testing.T) {
+	addresses := []Address{
+		{IP: "10.0.0.10", Port: "8080", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "80", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "443", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "53", Proto: "udp"},
+		{IP: "10.0.0.10", Port: "53", Proto: "tcp"},
+	}
+
+	// Port sorts numerically (not lexically: "443" must not sort before "80"),
+	// with Proto as the tie-breaker for equal ports (53/tcp before 53/udp).
+	want := []Address{
+		{IP: "10.0.0.10", Port: "53", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "53", Proto: "udp"},
+		{IP: "10.0.0.10", Port: "80", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "443", Proto: "tcp"},
+		{IP: "10.0.0.10", Port: "8080", Proto: "tcp"},
+	}
+
+	sortAddresses(addresses)
+	assert.Equal(t, want, addresses)
+}
+
+func TestGetContainerAddressesSorted(t *testing.T) {
+	testContainer := &docker.Container{
+		Config: &docker.Config{
+			ExposedPorts: map[docker.Port]struct{}{},
+		},
+		NetworkSettings: &docker.NetworkSettings{
+			IPAddress: "10.0.0.10",
+			Ports:     map[docker.Port][]docker.PortBinding{},
+		},
+	}
+	// Insert ports out of numeric order; the map iteration order is random but
+	// GetContainerAddresses must return them deterministically sorted by port.
+	testContainer.NetworkSettings.Ports[httpTestPort] = []docker.PortBinding{} // 8080
+	testContainer.NetworkSettings.Ports[httpPort] = []docker.PortBinding{}     // 80
+	testContainer.NetworkSettings.Ports[httpsPort] = []docker.PortBinding{}    // 443
+
+	addresses := GetContainerAddresses(testContainer)
+	ports := make([]string, len(addresses))
+	for i, a := range addresses {
+		ports[i] = a.Port
+	}
+	assert.Equal(t, []string{"80", "443", "8080"}, ports)
+}

internal/generator/generator.go

@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"os/signal"
+	"sort"
 	"strings"
 	"sync"
 	"syscall"
@@ -388,6 +389,15 @@ func (g *generator) sendSignalToFilteredContainers(config config.Config) {
 	}
 }
 
+// sortNetworks sorts networks in place by Name (ascending). Name is the docker
+// network name (the NetworkSettings.Networks map key), so it is unique and
+// non-empty, giving a stable total order.
+func sortNetworks(networks []context.Network) {
+	sort.Slice(networks, func(i, j int) bool {
+		return networks[i].Name < networks[j].Name
+	})
+}
+
 func (g *generator) getContainers(config config.Config) ([]*context.RuntimeContainer, error) {
 	apiInfo, err := g.Client.Info()
 	if err != nil {
@@ -474,6 +484,12 @@ func (g *generator) getContainers(config config.Config) ([]*context.RuntimeConta
 				network)
 		}
 
+		// NetworkSettings.Networks is a Go map, so the slice built above has a
+		// random order. Sort it deterministically so generated output is stable
+		// across regenerations (issue #431) and `index .Networks 0` is
+		// predictable / selectable by name (issue #169).
+		sortNetworks(runtimeContainer.Networks)
+
 		for k, v := range container.Volumes {
 			runtimeContainer.Volumes[k] = context.Volume{
 				Path:      k,

internal/generator/generator_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/nginx-proxy/docker-gen/internal/config"
 	"github.com/nginx-proxy/docker-gen/internal/context"
 	"github.com/nginx-proxy/docker-gen/internal/dockerclient"
+	"github.com/stretchr/testify/assert"
 )
 
 func TestGenerateFromEvents(t *testing.T) {
@@ -216,3 +217,32 @@ func TestGenerateFromEvents(t *testing.T) {
 		}
 	}
 }
+
+func TestSortNetworks(t *testing.T) {
+	for _, tc := range []struct {
+		desc string
+		in   []context.Network
+		want []context.Network
+	}{
+		{
+			desc: "multiple unsorted",
+			in:   []context.Network{{Name: "frontend"}, {Name: "bridge"}, {Name: "app_net"}},
+			want: []context.Network{{Name: "app_net"}, {Name: "bridge"}, {Name: "frontend"}},
+		},
+		{
+			desc: "single element",
+			in:   []context.Network{{Name: "bridge"}},
+			want: []context.Network{{Name: "bridge"}},
+		},
+		{
+			desc: "empty",
+			in:   []context.Network{},
+			want: []context.Network{},
+		},
+	} {
+		t.Run(tc.desc, func(t *testing.T) {
+			sortNetworks(tc.in)
+			assert.Equal(t, tc.want, tc.in)
+		})
+	}
+}