evicertia/dockernet-access-server repository overview

⁠dockernet-access-server

A Docker container that exposes Docker's internal bridge network to the host machine by bundling an OpenVPN server and a DNS server (dnsmasq). Connect from your host via any OpenVPN client and resolve running containers by name.

Two deployment modes are supported:

• Single container -- builds from Dockerfile, runs both OpenVPN and DNS via supervisord in a single image.
• Compose split -- uses docker-compose.yml to run DNS and OpenVPN as separate containers with different base images.

⁠Prerequisites

• Docker (with BuildKit support for building from source)
• An OpenVPN client such as Tunnelblick⁠ (macOS) or Viscosity⁠

⁠Quick Start: Single Container

Add the following service to your project's docker-compose.yml:

services:

  tunnel:
    image: evicertia/dockernet-access-server
    hostname: dockernet-access-server
    domainname: myapp.test
    init: true
    network_mode: myapp
    ports:
      - "1194:1194/udp"
    cap_add:
      - NET_ADMIN
    sysctls:
      net.ipv6.conf.default.forwarding: 1
      net.ipv6.conf.all.forwarding: 1
      net.ipv6.conf.all.disable_ipv6: 0
    environment:
      DNS_DOMAIN: ~
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./.tunnel:/etc/openvpn
    healthcheck:
      test: ["CMD-SHELL", "nc -w0 -z -n 127.0.0.1 53"]
      interval: 5s
      timeout: 1s
      retries: 3

networks:
  myapp:
    driver: bridge

To build the image from source instead of pulling from Docker Hub:

make build    # tags with git short-hash + latest

⁠Quick Start: Compose Split

The included docker-compose.yml runs DNS and OpenVPN as separate containers. This is useful for development of the tool itself:

docker-compose up -d
docker-compose logs -f

⁠Connecting

On first startup the container generates a PKI and writes a client profile to the mounted volume. For the single-container example above, look for .tunnel/dockernet.ovpn. Import this file into your OpenVPN client.

Once connected you should be able to:

• Reach containers on the Docker bridge network by IP.
• Resolve running container names via the built-in DNS server.

⁠Environment Variables

⁠Docker Image

• Image: evicertia/dockernet-access-server
• Base: kylemanna/openvpn:latest (Alpine Linux)
• Ports: 53/udp, 53/tcp (DNS), 1194/udp (OpenVPN)
• Volume: /etc/openvpn -- PKI and config persistence

⁠Security

The conf/ directory is gitignored and contains PKI private keys and certificates -- never commit its contents. The container runs as root, which is required for network manipulation and binding to port 53. The Docker socket is mounted read-only but still grants container discovery access.

⁠Credits

Based on previous work by:

• kylemanna/docker-openvpn⁠
• wojas/docker-mac-network⁠
• fardjad/docker-network-exposer⁠
• ruudud/devdns⁠

⁠License

MIT⁠