Polari
Running an isle

How Isle-Mesh is put together

Source
Isle-Mesh/PROJECT-STRUCTURE.md in the suite repository. This page is generated from it; edits go there.

This document explains the organization and purpose of directories in the Isle-Mesh project.

Directory Overview

IsleMesh/
├── isle-cli/              # CLI tool for mesh-app automation
├── mesh-prototypes/       # Hand-crafted reference implementations
├── test-mesh-apps/        # CLI-generated test cases
├── mesh-proxy/            # Nginx proxy automation
├── embed-jinja/           # Template-based configuration system
├── mdns/                  # mDNS system for service discovery
├── ssl/                   # SSL certificate utilities
└── [other files]          # Documentation, diagrams, configs

Core Directories

/isle-cli - CLI Tool

Purpose: The main command-line interface for Isle-Mesh

Contents:

  • Command scripts (init, up, down, prune, logs, ps, config, etc.)
  • Scaffold tool for converting docker-compose to mesh-apps
  • Configuration management

Usage: See GETTING-STARTED.md

Key Files:

  • index.js - Main CLI entry point
  • scripts/isle-core.sh - Core commands (init, up, down, etc.)
  • scripts/scaffold.sh - Docker compose conversion
  • scripts/config.sh - Configuration management

/mesh-prototypes - Reference Implementations

Purpose: Hand-crafted prototypes built WITHOUT the CLI

Why Hand-Crafted?:

  • Understand inner workings of mesh networking
  • Validate functionality before automating
  • Serve as reference for CLI development
  • Document best practices

Contents:

  • localhost-mdns/ - Local development mesh with mDNS
  • isle/ - VLAN-based mesh prototypes
  • planned-work/ - Future prototype concepts

Important: These are intentionally NOT generated by the CLI tool

/test-mesh-apps - CLI Test Cases

Purpose: Automated test applications built WITH the CLI

Why CLI-Generated?:

  • Validate CLI automation
  • Test different configurations
  • Provide usage examples
  • Integration testing

Contents:

  • Each subdirectory is a complete test case
  • Generated using isle init or isle scaffold

Creating Test Cases:

cd test-mesh-apps
mkdir my-test-case
cd my-test-case
isle init -d test.local

Important: All test apps should be created using the CLI

/mesh-proxy - Proxy Automation

Purpose: Automated nginx reverse proxy configuration

Key Features:

  • Jinja2 template-based configuration
  • Docker-compose parser
  • SSL/TLS and mTLS support
  • Subdomain routing

Main Components:

  • scripts/build-proxy-config.py - Configuration builder
  • templates/ - Nginx config templates
  • segments/ - Reusable config segments

/embed-jinja - Template System

Purpose: Framework for embedding Jinja templates in configuration files

Key Features:

  • Inline template syntax
  • Environment-based rendering
  • Automated build workflows
  • Multi-project support

Main Components:

  • ansible-orchestration/ - Build automation
  • setup.yml - Environment configuration
  • docker-compose.auto.yml - Automated workflow

/mdns - Service Discovery

Purpose: mDNS system for local service discovery

Features:

  • .local domain resolution
  • Service advertising
  • Host system integration

/ssl - SSL Utilities

Purpose: SSL certificate generation and management

Key Features:

  • Self-signed certificate generation
  • Multi-subdomain support
  • Mesh-wide SSL configuration

Key Distinction: Prototypes vs Test Apps

Prototypes (/mesh-prototypes)

  • ✋ Hand-crafted (no CLI)
  • 📚 Reference implementations
  • 🔬 Research and validation
  • 📖 Learning materials

Test Apps (/test-mesh-apps)

  • 🤖 CLI-generated (using isle commands)
  • ✅ Test automation
  • 📊 Integration testing
  • 📝 Usage examples

Development Workflow

Working on Prototypes

cd mesh-prototypes/my-prototype
# Manually create all configuration
# Test and validate functionality
# Document learnings

Creating Test Cases

cd test-mesh-apps/my-test
# Use CLI to generate
isle init -d test.local
# Validate CLI output
# Document test results

Developing CLI Features

# 1. Create prototype manually
cd mesh-prototypes/new-feature

# 2. Understand the manual process
# ... hand-craft configuration ...

# 3. Automate in CLI
cd isle-cli/scripts
# ... implement automation ...

# 4. Test with test-mesh-apps
cd test-mesh-apps/feature-test
isle init
# Validate automation works

Documentation

  • GETTING-STARTED.md - CLI quick start guide
  • PROJECT-STRUCTURE.md - This file
  • mesh-prototypes/README.md - Prototype documentation
  • test-mesh-apps/README.md - Test case documentation
  • Individual README files in each directory

Questions?

  • "Where are reference implementations?" → /mesh-prototypes
  • "How do I use the CLI?" → See GETTING-STARTED.md
  • "How do I create a test case?" → cd test-mesh-apps && isle init
  • "Where's the CLI source?" → /isle-cli
  • GETTING-STARTED.md - User guide for the CLI
  • Network-Diagram-Basic.drawio - Network topology diagrams
  • Isle-Mesh-Progression-Path.drawio - Development roadmap
  • setup.yml - Project-level configuration
  • isle-mesh.yml - Mesh network configuration

← All documentation