Polari
Networking and topology

Dual-domain access

Source
Isle-Mesh/isle-cli/DUAL-DOMAIN-SUPPORT.md in the suite repository. This page is generated from it; edits go there.

The Isle CLI (isle app init and isle app scaffold) now automatically generates nginx configurations that respond to both .local and .isle domains for seamless integration with the Isle Mesh join protocol.

What Changed

Automatic Dual-Domain nginx Configs

When you use isle app init or isle app scaffold with a .local domain, the generated nginx configurations will automatically include both the .local and .isle variants in server_name directives.

Example:

isle app init -d myapp.local

Generated nginx configuration:

server {
    listen 80;
    # Dual-domain support: mDNS (.local) and mesh DNS (.isle)
    server_name myapp.local myapp.isle;

    location / {
        # Your configuration
    }
}

server {
    listen 443 ssl;
    # Dual-domain support: mDNS (.local) and mesh DNS (.isle)
    server_name frontend.myapp.local frontend.myapp.isle;

    ssl_certificate /ssl/certs/myapp.crt;
    ssl_certificate_key /ssl/keys/myapp.key;

    location / {
        proxy_pass http://frontend;
    }
}

Usage

Initialize a New Mesh App

# Basic initialization with dual-domain support
isle app init -d myapp.local

# Convert existing docker-compose with dual-domain
isle app init -f docker-compose.yml -d myapp.local

# Full customization
isle app init -f app.yml -d myapp.local -n myproject -o ./output

Scaffold Existing Docker Compose

# Scaffold with default domain
isle app scaffold docker-compose.yml

# Scaffold with custom domain
isle app scaffold docker-compose.yml -d myapp.local -o ./mesh-output

# Scaffold with specific project name
isle app scaffold ./app/docker-compose.yml -n myapp -d myapp.local

How It Works

Template System

The CLI uses Jinja2 templates located in /mesh-proxy/segments/ to generate nginx configurations. Each template now includes conditional logic to add .isle domains when the base domain ends with .local:

HTTP Subdomain Template (server-http-subdomain.conf.j2):

server {
    listen 80;
    # Dual-domain support: mDNS (.local) and mesh DNS (.isle)
    server_name {{ subdomain }}.{{ base_domain }} {% if base_domain.endswith('.local') %}{{ subdomain }}.{{ base_domain.replace('.local', '.isle') }}{% endif %};

    location / {
        proxy_pass http://{{ upstream_name }};
    }
}

Generated Configuration Example

For a service backend with domain mesh-app.local, the CLI generates:

server {
    listen 80;
    server_name backend.mesh-app.local backend.mesh-app.isle;
    # ...
}

server {
    listen 443 ssl;
    server_name backend.mesh-app.local backend.mesh-app.isle;
    # ...
}

Integration with Join Protocol

The dual-domain nginx configs work seamlessly with the Isle Mesh join protocol:

  1. Agent advertises myserver.local via mDNS
  2. Join protocol discovers and creates DNS mapping for myserver.isle
  3. nginx responds to both domains with the same configuration
  4. Users can access via either:
    • http://myserver.local (mDNS)
    • http://myserver.isle (Mesh DNS)

Updated Templates

The following nginx template segments now include dual-domain support:

  • server-http-base.conf.j2 - Base domain HTTP server
  • server-https-base.conf.j2 - Base domain HTTPS server
  • server-http-subdomain.conf.j2 - Subdomain HTTP servers
  • server-https-subdomain-simple.conf.j2 - Subdomain HTTPS (no mTLS)
  • server-https-subdomain-mtls.conf.j2 - Subdomain HTTPS with mTLS

Examples

Example 1: Simple Web App

# Create project
mkdir my-web-app && cd my-web-app
isle app init -d webapp.local

# Edit docker-compose.mesh-app.yml to add services
# Then start the mesh app
isle app up --build

Result:

  • Services accessible via both frontend.webapp.local and frontend.webapp.isle
  • Automatic SSL support for both domains
  • Join protocol auto-discovers and maps domains

Example 2: Convert Existing App

# You have docker-compose.yml with services: frontend, backend, db
isle app scaffold docker-compose.yml -d myapp.local -o ./mesh-app

# Generated nginx config includes:
# - myapp.local / myapp.isle
# - frontend.myapp.local / frontend.myapp.isle
# - backend.myapp.local / backend.myapp.isle

Example 3: Multi-Service Mesh

# Initialize with custom name
isle app init -d services.local -n my-microservices

# Add services to docker-compose.mesh-app.yml:
# - api-gateway
# - user-service
# - auth-service
# - database

# All services will be accessible via both .local and .isle

Testing Dual-Domain Support

After running isle app init or isle app scaffold:

  1. Check generated nginx config: ``bash cat proxy/nginx-mesh-proxy.conf # Look for server_name directives with both .local and .isle
  1. Start the mesh app: ``bash isle app up --build
  1. Test .local domain: ``bash curl http://frontend.myapp.local
  1. Wait for join protocol (30 seconds max)
  1. Test .isle domain: ``bash curl http://frontend.myapp.isle

Both should return the same content!

Non-.local Domains

If you use a domain that doesn't end in .local, the CLI will only generate single-domain configs:

# Using .com domain
isle app init -d myapp.com

# Generated nginx config:
# server_name myapp.com (no .isle variant)

This is intentional - the .isle suffix is only added for mDNS-compatible .local domains that integrate with the join protocol.

Troubleshooting

nginx Shows Only .local Domain

If generated configs only show .local domains:

  1. Verify you used a .local domain: ``bash grep "domain:" setup.yml # Should show: domain: myapp.local
  1. Regenerate configs: ``bash # Re-run scaffold isle app scaffold docker-compose.yml -d myapp.local
  1. Check template files in /mesh-proxy/segments/ for dual-domain logic

.isle Domain Not Resolving

If .local works but .isle doesn't:

  1. Ensure join protocol is running on router: ``bash ssh root@192.168.1.1 '/etc/init.d/isle-join-protocol status'
  1. Check DNS mappings: ``bash ssh root@192.168.1.1 'cat /etc/dnsmasq.d/isle-vlan-domains.conf'
  1. Verify agent is advertising mDNS: ``bash docker exec isle-agent-mdns avahi-browse -a -t

Advanced Usage

Custom Domain Suffix

To use a different suffix than .isle, modify the template files:

  1. Edit /mesh-proxy/segments/server-http-subdomain.conf.j2
  2. Change .replace('.local', '.isle') to .replace('.local', '.mesh')
  3. Update join protocol to use .mesh instead of .isle

SSL Certificates for .isle Domains

The same SSL certificates work for both domains:

ssl_certificate /ssl/certs/myapp.crt;
ssl_certificate_key /ssl/keys/myapp.key;

To generate wildcard certificates:

isle app ssl generate-mesh config/ssl.env.conf

This creates a certificate valid for:

  • *.myapp.local
  • *.myapp.isle (if SAN is configured)
  • Join Protocol - How domain mapping works
  • Isle Agent Dual-Domain (../isle-agent-mdns/scripts/configure-dual-domain.sh) - Agent configuration
  • Verification Script (../openwrt-router/scripts/router-setup/verify-join-protocol.sh) - Testing tools

Summary

The Isle CLI now automatically configures nginx to respond to both .local and .isle domains when you use a .local base domain. This enables:

  • Seamless mDNS integration - Services advertise via .local
  • Mesh DNS fallback - Same services accessible via .isle
  • Automatic discovery - Join protocol handles domain mapping
  • Zero configuration - Works out of the box with isle app init

Just use .local domains and the CLI handles the rest!

← All documentation