DOCSEARCHbyAlgolia
Submit Docs

autoxpose

repository·main·Indexed 40 days ago

https://github.com/mostafa-wahied/autoxpose

A tool for automatic DNS and reverse proxy configuration for Docker containers. It automates the creation of DNS records and SSL-enabled proxy hosts using container labels. Supports Cloudflare for DNS management and Nginx Proxy Manager (NPM) or Caddy as proxy providers. Version 0.5.2.

Tokens
20K
Snippets
71
Records
88
Agent score
100%

What's inside autoxpose

  1. Understanding Auto-Expose modes

    main

    The autoxpose.enable label accepts two distinct modes that determine how a service is handled after discovery:

    • true: The service is discovered and displayed in the Auto-Expose UI, but it remains inactive until you manually click the "Expose" button.
    • auto: The service is discovered and automatically exposed immediately without requiring any manual UI interaction.
    # Example of auto-mode
labels:
  - autoxpose.enable=auto

  2. Quick Start: Deploy autoxpose via Docker Compose

    main

    The recommended way to deploy autoxpose is using Docker Compose. You must provide your public IP for DNS records and your LAN IP for proxy targets. The container requires access to the Docker socket to discover other containers.

    1. Create a docker-compose.yml file with the following content:
    2. Replace your-public-ip and your-lan-ip with your actual IP addresses.
    3. Run docker-compose up -d to deploy.
    services:
  autoxpose:
    image: mostafawahied/autoxpose:latest
    ports:
      - '4949:3000'
    environment:
      - SERVER_IP=your-public-ip
      - LAN_IP=your-lan-ip
    volumes:
      - autoxpose-data:/app/packages/backend/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

volumes:
  autoxpose-data:

  3. Configure Caddy Proxy Provider

    main

    To use Caddy as your proxy provider:

    1. Ensure Caddy is running with its API enabled (default port 2019).
    2. Verify API accessibility via curl http://server-ip:caddy-port/config/.
    3. In the autoxpose UI, navigate to Settings → Proxy Provider → Caddy.
    4. Provide the API URL (e.g., http://server-ip:caddy-port).

    Security Note: Caddy API has no authentication by default. Do not expose the Caddy API port to the public internet.

  4. Configure Nginx Proxy Manager (NPM) Provider

    main

    To use Nginx Proxy Manager as your proxy provider:

    1. Ensure NPM is running and accessible.
    2. In the autoxpose UI, navigate to Settings → Proxy Provider → NPM.
    3. Provide the following details:
      • URL: The NPM URL (e.g., http://server-ip:npm-port).
      • Username: Your NPM admin email.
      • Password: Your NPM password.

  5. Configure autoxpose via Container Labels

    main

    Autoxpose discovers services by scanning Docker containers for specific labels.

    • autoxpose.enable=true: Enables exposure for the container.
    • autoxpose.enable=auto: Automatically exposes the service when discovered.
    • autoxpose.subdomain=myapp: Sets a custom subdomain (defaults to the container name if not provided).

    Note: Labels cannot be added to running containers; you must recreate the container to apply them.

    # Docker Compose example
services:
  myapp:
    image: myapp:latest
    labels:
      - autoxpose.enable=true
      - autoxpose.subdomain=myapp
    # Docker CLI example
docker run -d \
  --name myapp \
  --label autoxpose.enable=true \
  --label autoxpose.subdomain=myapp \
  myapp:latest

  6. Use a Docker Socket Proxy for enhanced security

    main

    Instead of mounting /var/run/docker.sock directly into autoxpose, you can use a read-only tecnativa/docker-socket-proxy to limit access. When using this method, you must set the DOCKER_HOST environment variable in autoxpose to point to the proxy container.

    services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy:latest
    restart: unless-stopped
    environment:
      - CONTAINERS=1
      - EVENTS=1
      - INFO=1
      - NETWORKS=1
      - POST=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - '2375:2375'

  autoxpose:
    image: mostafawahied/autoxpose:latest
    ports:
      - '4949:3000'
    environment:
      - SERVER_IP=203.0.113.50
      - LAN_IP=192.168.1.100
      - DOCKER_HOST=tcp://docker-proxy:2375
    volumes:
      - autoxpose-data:/app/packages/backend/data
    depends_on:
      - docker-proxy

volumes:
  autoxpose-data:

  7. Quick Start: Deploy autoxpose via Docker Run

    main

    You can run autoxpose as a standalone container using the docker run command. Ensure you pass the required SERVER_IP and LAN_IP environment variables and mount the Docker socket.

    docker run -d \
  --name autoxpose \
  --restart unless-stopped \
  -p 4949:3000 \
  -e SERVER_IP=your-public-ip \
  -e LAN_IP=your-lan-ip \
  -v autoxpose-data:/app/packages/backend/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  mostafawahied/autoxpose:latest

  8. Configure Cloudflare DNS Provider

    main

    To use Cloudflare for DNS management, follow these steps:

    1. In the Cloudflare Dashboard, go to My Profile → API Tokens.
    2. Create a token using the Edit zone DNS template.
    3. Ensure permissions are set to: Zone / DNS / Edit.
    4. Set Zone Resources to: Include / Specific zone / yourdomain.com.
    5. Copy the generated token.
    6. In the autoxpose UI, navigate to Settings → DNS Provider → Cloudflare, paste the token, and enter your domain.

  9. Manage exposure progress with ExposeContext

    main

    The ExposeContext interface is used to track and report the progress of exposure tasks (DNS or Proxy) to the user/frontend.

    Properties:

    • serviceId: Unique identifier for the service being processed.
    • action: Either 'expose' or 'unexpose'.
    • steps: An array of ProgressStep objects representing the current state of DNS and Proxy tasks.
    • onProgress: A callback function (ProgressCallback) that receives ProgressEvent objects to update the UI.

    Event Types:

    • progress: Ongoing updates with current steps and timestamps.
    • complete: Successful completion with a result object containing domain, dnsRecordId, proxyHostId, and SSL status.
    • error: Failure with a result object containing the error message.
    export interface ExposeContext {
  serviceId: string;
  action: 'expose' | 'unexpose';
  steps: ProgressStep[];
  onProgress: (event: ProgressEvent) => void;
}

  10. Configure autoxpose Environment Variables

    main

    The following environment variables can be used during deployment:

    VariableDescriptionRequired
    SERVER_IPPublic IP or hostname for DNS A recordsYes
    LAN_IPLAN/private IP for proxy targets (auto-detected as fallback)Yes
    DOCKER_HOSTTCP endpoint when using a socket proxyNo
    LOG_LEVELLogging level: debug, info, warn, errorNo

    Note: DNS and proxy providers are primarily configured through the web UI.

  11. Understand the progress data structures

    main

    When monitoring or handling real-time updates from the backend, the frontend uses specific types to represent the lifecycle of an 'expose' or 'unexpose' action. Progress is tracked through phases, statuses, and events.

    Progress Phases

    An operation moves through these specific phases:

    • dns: DNS record configuration.
    • proxy: Proxy configuration.

    Progress Statuses

    Each step in a phase can have one of the following statuses:

    • pending: The step is waiting to start.
    • running: The step is currently in progress.
    • success: The step completed successfully.
    • error: The step failed.
    • warning: The step completed but with non-critical issues.

    Progress Event Structure

    Progress updates are delivered via ProgressEvent objects, which include the serviceId, the action being performed, a list of steps, and an optional result upon completion.

    // Example of a ProgressEvent structure
const event: ProgressEvent = {
  type: 'progress',
  serviceId: 'svc_123',
  action: 'expose',
  steps: [
    { phase: 'dns', status: 'success', progress: 100, message: 'DNS record created' },
    { phase: 'proxy', status: 'running', progress: 45, message: 'Configuring proxy' }
  ],
  timestamp: 1672531200000
};

  12. Manage Wildcard Mode settings

    main

    The frontend provides components to manage the transition between standard DNS configuration and Wildcard Mode:

    • WildcardModeDisplay: Shows the current status of Wildcard Mode, including the active wildcard domain (e.g., *.domain.com), whether DNS is skipped, and whether an SSL certificate is linked. It provides a button to Switch to DNS mode.
    • WildcardChoiceSection: Provides the interface to enable Wildcard Mode. It can automatically detect a domain from Nginx Proxy Manager (NPM) or allow manual input via a Wildcard domain field. It displays whether the detected domain matches the current configuration.
    • DnsHeader: A status indicator that displays whether the DNS provider is configured or in wildcard mode.
    • DnsDisabledState: A fallback UI shown when DNS cannot be configured because the proxy has not been set up yet.