Pods are a powerful configuration and inheritance system in Doh that serves as the backbone for application settings, module configuration, and environment-specific configurations. The Pod system allows for sophisticated configuration management across different environments with support for inheritance, type validation, and secure separation of sensitive data.

This guide covers:

• Core concepts of pod files and hierarchy
• Type safety with MOC validation
• Pod system components and namespaces
• Boot process and configuration loading
• Host load configuration
• Pod caching and manifests
• CLI commands for pod management
• Pod dashboard and monitoring

Core Concepts

Pod Files

The Pod system revolves around several key files:

1. boot.pod.yaml: The application-level settings file that defines which modules to load on startup and core application configuration. This file should be version controlled and contains shared application settings.

2. pod.yaml: The local developer settings file, typically nearly empty and used for environment-specific overrides like local hosting configurations or staging setups. This file is usually ignored in version control.

3. Module Pods: Module-specific configuration defined through Doh.Pod() calls, stored in manifest files.

Pod Hierarchy and Inheritance

Pods implement a flexible inheritance model using the inherits property:

inherits:
  - /path/to/base.pod.yaml
  - https://example.com/shared.pod.yaml
  - /pods/custom-config.pod.yaml

This allows for configuration composition where settings cascade from base configurations to more specific ones. The inheritance chain is resolved using the build_pod function, which processes all inherited pods recursively.

Pod Namespaces

Pods maintain two primary namespaces:

1. Doh.pod: The complete pod configuration, including server-only settings, available only in Node.js environments.

2. Doh.browser_pod: A subset of pod settings that are safe to expose to browser clients. In browser environments, Doh.pod is equivalent to Doh.browser_pod.

Type Safety with MOC

The Pod system uses Melded Object Composition (MOC) to provide type safety for configuration values. The moc property in a pod defines type validation for its properties:

moc:
  apiUrl: 'IsString'
  timeout: 'IsNumber'
  retries: 'IsInt'
  settings: 
    debug: 'IsBoolean'
    logLevel: 'IsString'

This ensures that configuration values conform to expected types and can be validated at runtime. All MOC validation operators are available for pod configuration, including composite types and validation rules.

Pod System Components

Doh.pod

The global object containing all pod settings merged from boot.pod.yaml, pod.yaml, and module pods. It is the primary way to access configuration values in server-side code:

const port = Doh.pod.express_config.port;
const apiKey = Doh.pod.api_keys.service_name;

Doh.browser_pod

A subset of Doh.pod that contains only browser-safe configuration values. This is made available to browser clients and excludes sensitive server-only configuration:

// In Node.js, both are available
console.log(Doh.pod.private_setting);      // Available
console.log(Doh.browser_pod.api_endpoint); // Available

// In browser, only browser_pod settings are available
console.log(Doh.pod.api_endpoint);         // Available in browser
console.log(Doh.pod.private_setting);      // Undefined in browser

Doh.Pod()

A function to define module-specific pod configuration:

Doh.Pod('my_module', {
  moc: {
    setting1: 'IsString',
    setting2: 'IsNumber'
  },
  setting1: 'default value',
  setting2: 100,
  
  // Browser-safe settings
  browser_pod: {
    publicUrl: '/api/module'
  }
});

These module pods are merged into the main pod configuration and follow the same inheritance rules.

The Boot Process

When Doh starts, it processes pod files in a specific order:

1. Loads core defaults from /doh_js/default.pod.yaml
2. Loads module-specific pods from Doh.Pod() definitions
3. Loads application settings from /boot.pod.yaml
4. Loads local environment settings from /pod.yaml
5. Compiles everything into a unified Doh.pod object

This process ensures that local settings override application settings, which override defaults.

host_load Configuration

The host_load property in pods defines which packages should be automatically loaded when the application starts:

host_load:
  - user_routes
  - socket_handler
  - api_module
  - dashboard

This provides a declarative way to define your application's entry points without needing to manually load modules in code.

dohball_host Configuration

The dohball_host property defines which remote Doh instances should be used as sources for installing and upgrading remotely hosted Dohballs. This enables HTTP-based distribution of Dohballs without requiring Git. Note that this is ONLY for consuming code from external hosts - local code in your project is handled automatically by the Auto-Packager without any installation.

dohball_host:
  - https://backup-host.com
  - https://your-team-host.com
  - http://localhost:3001

How dohball_host Works

1. Remote Installation Only: doh install and doh upgrade commands ONLY work with remote hosts configured here
2. Local Code is Automatic: Code in your own project doesn't need installation - the Auto-Packager handles it automatically
3. Direct HTTP Installation: When you run doh install package_name, Doh searches through the configured hosts in order
4. Automatic Downloads: The last host that provides the requested package serves the .tar.gz file directly via HTTP
5. Version Comparison: doh upgrade compares locally installed versions with remote host versions to determine updates
6. Fallback Chain: Multiple hosts can be configured for redundancy - if the last host is unavailable, the next is tried

Hosting Dohballs

To serve Dohballs via HTTP/S, configure a Doh instance as a host:

# In the hosting instance's pod.yaml
dohball_deployment:
  compile_manifest: true
host_load:
  - dohball_host  # Enable the dohball_host module

# The hosting instance will serve baked Dohballs at:
# https://your-host.com/dohball/package_name

Distribution Methods

Dohballs support two complementary distribution approaches:

• HTTP-Based (Direct): Using dohball_host for real-time distribution without Git
• Git-Based (Traditional): Committing baked artifacts to Git repositories for transport

Both methods can be used simultaneously, and consumers can mix and match based on their needs.

Pod Caching and Manifests

The Pod system uses several manifest files to optimize performance:

1. /.doh/manifests/pod_manifest.json: Contains module pod settings compiled from Doh.Pod() calls
2. /doh_js/manifests/browser_pod.json: Contains browser-safe pod settings
3. /.doh/compiled.pod.yaml: A cache of the full compiled pod

These files are automatically managed by the Doh runtime and can be cleared with CLI commands when needed.

CLI Commands for Pod Management

Doh provides a unified CLI system for managing pod configurations with intelligent array detection and consistent syntax:

Unified Pod Commands

View and Set Pod Values

# Show current value and inheritance chain
doh pod express_config.port
doh bootpod host_load

# Set values
doh pod express_config.port 3000
doh bootpod debug_mode true

# Add compile-time removal directives
doh pod ~~express_config.debug
doh bootpod ~~host_load

Array Management

Arrays are automatically detected via MOC metadata or existing values. The system provides consistent syntax:

# Add to arrays
doh pod inherits /path/to/pod.yaml
doh pod dohball_host https://host.com
doh bootpod host_load package1

# Remove from arrays immediately
doh pod inherits ~/path/to/pod.yaml
doh pod dohball_host ~https://host.com
doh bootpod host_load ~package1

Backward Compatibility Commands

The following commands are maintained for backward compatibility but route through the unified system:

Manage Inheritance (Legacy)

# Add inheritance (routes to: doh pod inherits /path/to/pod.yaml)
doh inherits /path/to/pod.yaml

# Remove inheritance immediately (routes to: doh pod inherits ~/path/to/pod.yaml)
doh inherits ~/path/to/pod.yaml

Manage Host Load (Legacy)

# Add packages to host_load (routes to: doh bootpod host_load package1 package2)
doh host_load package1 package2

# Remove packages from host_load immediately (routes to: doh bootpod host_load ~package1 ~package2)
doh host_load ~package1 ~package2

Manage Dohball Hosts (Legacy)

# Add host (routes to: doh pod dohball_host https://host.com)
doh dohball_host https://host.com

# Remove host immediately (routes to: doh pod dohball_host ~https://host.com)
doh dohball_host ~https://host.com

Cache Management

# Clear pod cache
doh clear-pod

# Clear all caches
doh clear-all

Syntax Guide

The unified pod system uses consistent syntax:

• ~value: Remove value immediately from file
• ~~setting: Add compile-time removal directive (e.g., ~~debug_mode: true)
• Arrays: Auto-detected via MOC metadata or existing values
• Cleanup: Empty arrays are automatically removed from files
• Files: doh pod edits /pod.yaml, doh bootpod edits /boot.pod.yaml

Pod Dashboard

The pod_dashboard module (if included in your application) provides a web interface for managing pod settings. It allows:

1. Viewing the full pod hierarchy
2. Editing pod values
3. Visualizing inheritance relationships
4. Testing MOC validation rules

Access it at /admin/pods in your application (with proper authentication).

Integration with MOC System

Pod validation leverages the full power of Doh's MOC system, allowing for sophisticated validation rules:

moc:
  # Basic Types
  stringValue: 'IsString'
  numberValue: 'IsNumber'
  
  # Composite Types
  configObject: 
    enabled: 'IsBoolean'
    level: 'IsInt'
    name: 'IsStringAndHasValue'
    
  # Advanced Validation
  domains: ['IsArray', 'NotNull']
  timeout: ['IsNumber', 'NotNull']
  database:
    url: 'IsKeySafe'
    maxConnections: 'IsIntOrFalse'

This validation ensures configuration correctness and helps prevent runtime errors.

Pod Security Best Practices

1. Separate Sensitive Data: Keep API keys, database credentials, and other sensitive information in separate pod files that are ignored in version control.

2. Use Browser_Pod Carefully: Only expose data to the browser that is truly necessary for client-side functionality.

3. Validate with MOC: Always define MOC validation rules for your configurations to catch errors early.

4. Structure Inheritance Wisely: Create logical layers of pod files:

   • Core application settings (boot.pod.yaml)
   • Environment-specific settings (prod.pod.yaml, dev.pod.yaml)
   • Local overrides (pod.yaml - not version controlled)

5. Use Path References: For file paths in pod settings, use relative paths with DohPath() in code to ensure cross-platform compatibility.

Example Pod Structure

Application Settings (boot.pod.yaml)

inherits:
  - /pods/app-defaults.pod.yaml

host_load:
  - user_routes
  - api_service
  - dashboard

app_version: '1.2.0'
app_name: 'My Doh Application'

express_config:
  port: 3000
  
browser_pod:
  api_base: '/api/v1'
  app_name: 'My Doh Application'

Local Settings (pod.yaml)

inherits:
  - /pods/localhost.pod.yaml
  - /pods/dev-secrets.pod.yaml

express_config:
  port: 4000  # Override the default port
  
debug_mode: true

Module Configuration (via Doh.Pod())

Doh.Pod('user_module', {
  moc: {
    user_settings: {
      max_sessions: 'IsInt',
      default_role: 'IsString'
    }
  },
  user_settings: {
    max_sessions: 5,
    default_role: 'user'
  },
  browser_pod: {
    login_url: '/auth/login'
  }
});