Support for Container Network Mode

[engels74]

Feature Request: Support for Container Network Mode

Problem Statement

Wings currently hardcodes the Hostname field when creating Docker containers, which prevents the use of network_mode: container:<name> in the Docker configuration. This limitation stems from a conflict between Docker's API requirements and Wings' container creation logic.

Current Behavior

When attempting to configure Wings with network_mode: container:<name> in config.yml:

docker:
  network:
    network_mode: container:caddy

Container creation fails with the following error:

ERROR: failed to create server environment during install process 
error=environment/docker: failed to create container: Error response from daemon: 
conflicting options: hostname and the network mode

Root Cause

The Docker API explicitly prohibits setting a custom hostname when using network_mode: container:<name> because containers sharing another container's network namespace must inherit that container's hostname. However, Wings unconditionally sets the hostname to the server UUID at line 181 in environment/docker/container.go:

conf := &container.Config{
    Hostname:     e.Id,  // Always set, regardless of network mode
    Domainname:   cfg.Docker.Domainname,
    // ...
}

This prevents game server containers from sharing another container's network namespace entirely.

Use Case

Scenario: VPN-Routed Game Servers

My deployment pattern involves routing game server traffic through a VPN connection to protect the host's IP address. This can be achieved by:

1. Running a VPN container (e.g., Caddy with WireGuard) on a Docker bridge network
2. Configuring game server containers to use network_mode: container:caddy to share the VPN container's network namespace
3. All game server traffic is then routed through the VPN connection

Example Network Configuration:

• Bridge network: caddy_backbone (172.20.0.0/24)
• VPN container: caddy with WireGuard connection
• Game servers: Should use network_mode: container:caddy to route through VPN

Current Workaround Limitations

The only current alternative is to use a standard bridge network (network_mode: caddy_backbone), but this does not route traffic through the VPN. Containers on the same bridge network are merely neighbors with independent internet connections.

Benefits

Supporting network_mode: container:<name> would enable:

• VPN Integration: Route traffic through a VPN container for IP protection and DDoS mitigation without exposing the host’s IP.
• Resource Efficiency: Reduces overhead by reusing an existing network stack instead of spawning additional network interfaces per container.
• Advanced Topologies: Allows containers to share networking contexts for sidecar patterns, debugging, or dependency coupling (e.g., game server ↔ proxy).
• Backward Compatibility: Default configurations remain unaffected. Only containers explicitly sharing a network namespace omit the hostname.

Proposed Solution

Add conditional logic to skip setting the hostname when using container network mode. The hostname should only be set when the container has its own network namespace.

Technical Details

Affected Files

• environment/docker/container.go (line 181): Game server container creation

Configuration

The network mode is read from the Wings configuration:

networkMode := container.NetworkMode(cfg.Docker.Network.Mode)

This value comes from config.yml:

docker:
  network:
    network_mode: container:caddy  # or any other container name

Docker API Constraint

From Docker's perspective, when using network_mode: container:<name>:

• The container shares the target container's network namespace entirely
• This includes network interfaces, IP addresses, ports, and hostname
• Setting a custom hostname creates an inconsistency and is therefore rejected

Compatibility

This change can be backward compatible:

• Existing configurations using bridge networks or default network mode will continue to work
• The hostname will still be set for all standard network configurations
• Only containers explicitly using network_mode: container:<name> will have the hostname omitted

References

• Docker API documentation on network modes
• Wings configuration: config/config_docker.go (DockerNetworkConfiguration struct)
• Container creation logic: environment/docker/container.go (Create function)

[engels74]

Fixed it myself on this branch: https://github.com/engels74/wings/tree/feat-networkMode-v2 / docker pull ghcr.io/engels74/wings:feat-networkMode-v2-docker. I'll create a Pull Request during this week.

See main...engels74:wings:feat-networkMode-v2 for details on the implementation.

Below is a config.yml example, that uses the caddy (which is behind a VPN) as the network_mode, using network_mode: container:caddy. With the fix from the feat-networkMode branch, it no longer conflicts with the error:

ERROR: failed to create server environment during install process 
error=environment/docker: failed to create container: Error response from daemon: 
conflicting options: hostname and the network mode

config.yml example:

debug: false
uuid: ((REDACTED))
token_id: ((REDACTED))
token: ((REDACTED))
api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: false
    cert: /etc/letsencrypt/live/wings.domain.com/fullchain.pem
    key: /etc/letsencrypt/live/wings.domain.com/privkey.pem
  upload_limit: 256
docker:
  network:
    interface: 172.20.0.1
    name: caddy_backbone
    network_mode: container:caddy
    interfaces:
      v4:
        subnet: 172.20.0.0/24
        gateway: 172.20.0.1
system:
  data: /var/lib/pelican/volumes
  sftp:
    bind_port: 2022
allowed_mounts: []
remote: 'http://panel.domain.com'
allowed_origins:
  - https://panel.domain.com