Skip to content

docker-integration.md

Latest commit

 

History

History
190 lines (135 loc) · 5.77 KB

docker-integration.md

File metadata and controls

190 lines (135 loc) · 5.77 KB
title Docker Auto-Discovery
description Automatically find and proxy Docker containers with one click
category integration

Docker Auto-Discovery

Already running apps in Docker? Charon automatically finds your containers and offers one-click proxy setup. Supports both local Docker installations and remote Docker servers.

Overview

Docker auto-discovery eliminates manual IP address hunting and port memorization. Charon queries the Docker API to list running containers, extracts their network information, and lets you create proxy configurations with a single click.

How It Works

  1. Charon connects to Docker via socket or TCP
  2. Queries running containers and their exposed ports
  3. Displays container list with network details
  4. You select a container and assign a domain
  5. Charon creates the proxy configuration automatically

Why Use This

Eliminate IP Address Hunting

  • No more running docker inspect to find container IPs
  • No more updating configs when containers restart with new IPs
  • Container name resolution handles dynamic addressing

Accelerate Development

  • Spin up a new service, proxy it in seconds
  • Test different versions by proxying multiple containers
  • Remove proxies as easily as you create them

Simplify Team Workflows

  • Developers create their own proxy entries
  • No central config file bottlenecks
  • Self-service infrastructure access

Configuration

Docker Socket Mounting

For Charon to discover containers, it needs Docker API access.

Docker Compose:

services:
  charon:
    image: charon:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Docker Run:

docker run -v /var/run/docker.sock:/var/run/docker.sock:ro charon

Security Note: The socket grants significant access. Use read-only mode (:ro) and consider Docker socket proxies for production.

Remote Docker Server Support

Connect to Docker hosts over TCP:

  1. Go to Settings → Docker
  2. Click Add Remote Host
  3. Enter connection details:
    • Name: Friendly identifier
    • Host: IP or hostname
    • Port: Docker API port (default: 2375/2376)
    • TLS: Enable for secure connections
  4. Upload TLS certificates if required
  5. Click Test Connection, then Save

Container Selection Workflow

Viewing Available Containers

  1. Navigate to Hosts → Add Host
  2. Click Select from Docker
  3. Choose Docker host (local or remote)
  4. Browse running containers

Container List Display

Each container shows:

  • Name: Container name
  • Image: Source image and tag
  • Ports: Exposed ports and mappings
  • Networks: Connected Docker networks
  • Status: Running, paused, etc.

Creating a Proxy

  1. Click a container row to select it
  2. If multiple ports are exposed, choose the target port
  3. Enter the domain name for this proxy
  4. Configure SSL options
  5. Click Create Host

Automatic Updates

When containers restart:

  • Charon continues proxying to the container name
  • Docker's internal DNS resolves the new IP
  • No manual intervention required

Advanced Configuration

Network Selection

If a container is on multiple networks, specify which network Charon should use for routing:

  1. Edit the host after creation
  2. Go to Advanced → Docker
  3. Select the preferred network

Port Override

Override the auto-detected port:

  1. Edit the host
  2. Change the backend URL port manually
  3. Useful for containers with non-standard port configurations

Troubleshooting

Issue Cause Solution
No containers shown Socket not mounted Add Docker socket volume
Connection refused Remote Docker not configured Enable TCP API on Docker host
Container not proxied Container not running Start the container
Wrong IP resolved Multi-network container Specify network in advanced settings
Socket proxy not reachable DOCKER_HOST misconfigured Verify socket-proxy container is on the same network and DOCKER_HOST matches the service name

Security Considerations

  • Socket Access: The Docker socket grants broad system access — the :ro flag prevents deleting the socket file, but does not restrict which Docker API calls can be made. If you don't need container auto-discovery, skip the socket mount entirely. For production, use a socket proxy (see below).
  • Remote Connections: Always use TLS for remote Docker hosts.
  • Network Isolation: Use Docker networks to segment container communication.

Limiting Socket Access with a Proxy

A Docker socket proxy sits between Charon and the Docker daemon, filtering API calls so only the endpoints Charon actually needs are reachable. Charon only uses GET /containers/* to list containers, so you can lock everything else down.

Recommended proxy: lscr.io/linuxserver/socket-proxy

services:
  socket-proxy:
    image: lscr.io/linuxserver/socket-proxy:latest
    container_name: socket-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1   # Allow container listing (required by Charon)
      - POST=0         # Deny all write operations
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - proxy-internal

  charon:
    image: ghcr.io/wikid82/charon:latest
    environment:
      - DOCKER_HOST=tcp://socket-proxy:2375
    # No docker.sock volume needed!
    networks:
      - proxy-internal
      - ...

networks:
  proxy-internal:
    internal: true

With this setup, Charon talks to the proxy instead of the raw Docker socket. The proxy only answers container listing requests — everything else is blocked.

Related