Containers

Run Docker containers alongside your TelemetryOS applications to provide backend services, databases, or complex processing capabilities on devices.

What are Containers?

Containers are Docker containers that run alongside your application on physical devices. They enable backend functionality that's not possible in browser contexts, such as:

• Backend APIs with databases
• Image processing services
• Machine learning inference
• Message queues (Redis, RabbitMQ)
• Local caching layers
• Custom protocol handlers

⚠️ RESOURCE WARNING

Containers run directly on device hardware and can exhaust all available system resources. It is entirely possible to install a container that consumes all RAM, CPU, or storage on a device, causing system instability or failure.

You are responsible for:

• Testing container resource usage on target devices before production deployment
• Ensuring containers stay within device resource limits (RAM, CPU, storage)
• Setting appropriate resource constraints in your container configuration
• Monitoring container performance in production environments

Always test containers on the actual device models you plan to deploy to. Resource availability varies significantly across device types.

Configuration

Containers are defined in your telemetry.config.json file:

{
  "name": "my-application",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render"
  },
  "containers": [
    {
      "name": "api-server",
      "image": "myapp/backend:latest",
      "port": 3000
    },
    {
      "name": "redis-cache",
      "image": "redis:7-alpine",
      "port": 6379
    }
  ]
}

Automatic Hostname Routing

Container names automatically become hostnames that your application can access:

// Container name: "api-server"
// Automatically available at: http://api-server

fetch('http://api-server:3000/api/data')
  .then(res => res.json())
  .then(data => displayData(data));

Key Characteristics

Device-Only

• Run on: Physical devices only
• Not available: Admin portal/settings view
• Applications must provide fallbacks when containers aren't available

Independent Lifecycle

• Start: When playlist containing app is loaded
• Run: Continuously while playlist is active
• Stop: When playlist is unloaded

No Persistent Storage

• Container data does NOT persist across restarts by default
• Use external storage or network mounts for persistence
• Plan for ephemeral data scenarios

Basic Example

telemetry.config.json:

{
  "name": "inventory-display",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render"
  },
  "containers": [
    {
      "name": "inventory-api",
      "image": "mycompany/inventory-api:v1.2",
      "port": 8080
    }
  ]
}

Application code:

import { configure } from '@telemetryos/sdk';

configure('inventory-display');

async function fetchInventory() {
  try {
    // Container hostname automatically resolves
    const response = await fetch('http://inventory-api:8080/inventory');
    const inventory = await response.json();
    displayInventory(inventory);
  } catch (error) {
    // Container might not be available (e.g., in admin portal)
    console.warn('Container not available, using fallback');
    displayFallback();
  }
}

Best Practices

1. Test Resource Usage First - Profile containers on target devices to verify RAM, CPU, and storage consumption before production deployment
2. Set Resource Constraints - Configure memory and CPU limits in container definitions to prevent resource exhaustion
3. Detect Availability - Containers only run on devices, not in admin portal
4. Provide Fallbacks - Handle scenarios where containers aren't available
5. Use Standard Ports - Avoid port conflicts between containers
6. Lightweight Images - Use Alpine-based or minimal images; devices have limited resources
7. Error Handling - Handle container failures gracefully
8. Public Images - Images must be publicly accessible or pre-loaded

Container vs Worker vs Render

Common Use Cases

• Backend APIs - Node.js, Python, Go services with databases
• Data Processing - ETL pipelines, data transformation
• Machine Learning - TensorFlow, PyTorch inference servers
• Caching - Redis, Memcached for performance
• Message Queues - RabbitMQ, NATS for async processing
• Media Processing - ffmpeg, ImageMagick for conversions

Communication Patterns

Application → Container

// HTTP requests from application to container
const data = await fetch('http://my-container:3000/api/data').then(r => r.json());

Container → Application

Containers cannot directly call application code. Use intermediate storage:

// Container writes to external storage/database
// Worker polls and updates SDK storage
// Application subscribes to storage changes
store().application.subscribe('data', (newData) => {
  updateDisplay(newData);
});

Limitations

• Resource Constraints - Limited by device CPU/memory; can exhaust device resources if not properly configured and tested
• No SDK Access - Containers cannot use TelemetryOS SDK
• Device-Only - Not available in admin portal/preview
• No Persistence - Data doesn't survive container restarts
• Network Isolation - Can only communicate via HTTP

Learn More

For comprehensive container documentation including:

• Complete lifecycle management
• Advanced configuration options
• Multiple container coordination
• Networking and security

See the Mount Points Guide in the SDK documentation.

Next Steps

• Mount Points - Complete architecture guide
• Configuration - Full telemetry.config.json reference
• Workers - Background JavaScript for device-side processing
• Rendering - Main application UI component