Defining Application

After building application code (typically using the CLI tool), the application definition in TelemetryOS Studio makes it available for deployment to devices. This process connects the code repository to the TelemetryOS platform.

Prerequisites

Application definition in Studio requires:

• ✅ Built the application code locally
• ✅ Tested it with tos serve or equivalent development server
• ✅ Created a telemetry.config.json configuration file
• ✅ Pushed the code to a Git repository (GitHub recommended) or created a ZIP archive

Accessing Application Creation

The application creation interface is accessible through Content > Applications > CREATE APPLICATION in TelemetryOS Studio at app.telemetryos.com.

The application creation interface provides multiple methods for connecting the application code to the platform.

Application Definition Methods

TelemetryOS Studio provides three methods for defining applications:

1. Import GitHub Repository (Recommended)

GitHub repository connection enables automated CI/CD deployment with version control integration.

Benefits:

• Automatic builds on git push
• Version history and rollback capability
• Branch-based deployment (staging/production)
• Team collaboration through pull requests
• Continuous integration workflow

Requirements:

• Application code pushed to GitHub
• TelemetryOS GitHub authorization (first-time only)
• Repository and branch selection
• Build settings (auto-detected from telemetry.config.json)

Learn more: GitHub Integration

2. Import Git Repository

Connect any Git repository (GitLab, Bitbucket, self-hosted) using HTTPS URL.

Benefits:

• Works with any Git hosting provider
• Same CI/CD capabilities as GitHub integration
• Version control and rollback
• Supports private repositories with authentication

Requirements:

• Application code pushed to Git provider
• Repository HTTPS URL
• Authentication credentials (for private repositories)
• Branch selection for deployment
• Build settings configuration

Learn more: Import Git Repositories

3. Upload Archive (ZIP)

Upload a pre-built ZIP file containing the application code.

Use cases:

• Quick testing and prototyping
• Internal applications without source control
• Pre-built applications from third parties
• Legacy applications or migrations

Requirements:

• Application built locally (npm run build)
• ZIP archive of the dist/ or build/ directory
• Application metadata configuration

Learn more: Upload a ZIP File

Required Configuration

Regardless of the method chosen, all applications require:

Application Metadata

Application Name

• Unique identifier within the account
• Used in SDK configure() call
• Should match the name field in telemetry.config.json

Version

• Semantic versioning recommended (e.g., 1.0.0)
• Incremented with each deployment
• Used for rollback and version management

Description (optional)

• User-facing description of application functionality
• Helps team members understand application purpose
• Shown in application library

Source Configuration

Repository/Archive Location

• GitHub repository URL or Git HTTPS URL
• Branch name for Git-based deployments
• ZIP file for archive uploads

Build Settings

• Build command (e.g., npm run build, auto-detected from package.json)
• Build output directory (e.g., dist/, auto-detected from telemetry.config.json)
• Node.js version (if applicable)

Mount Points

Mount points are automatically detected from telemetry.config.json:

{
  "name": "weather-dashboard",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

These tell TelemetryOS where to load each component of the application:

• render - Main display component shown on devices
• settings - Configuration UI shown in Studio side panel
• background - Worker scripts (optional)

Learn more: Mount Points

Application Definition Workflow

Building Locally

The CLI generates and develops applications:

# Generate new application
tos init weather-dashboard
cd weather-dashboard

# Develop and test locally
tos serve

# Build for production
npm run build

Repository Setup

Code commits to a Git repository:

git add .
git commit -m "Initial application build"
git remote add origin https://github.com/username/weather-dashboard.git
git push -u origin main

Studio Configuration

Application definition occurs through Content > Applications > CREATE APPLICATION using the Import GitHub Repository option. GitHub authorization is required for first-time connections.

Auto-detected settings include:

• Name: weather-dashboard (from telemetry.config.json)
• Build command: npm run build (from package.json)
• Output directory: dist/ (from Vite config)
• Mount points: /render, /settings (from telemetry.config.json)

Build Process

TelemetryOS automatically:

• Clones the repository
• Installs dependencies (npm install)
• Runs build command (npm run build)
• Packages application files
• Creates initial version (v1.0.0)

Build progress displays in real-time. Builds typically complete in 1-3 minutes.

Playlist Integration

Once built, applications are ready for deployment through Content > Playlists. Applications are added to playlist pages with instance settings configured in the side panel. Playlist assignment to devices or device groups enables content delivery.

Post-Definition Workflow

Continuous Deployment

GitHub/Git integration enables automatic updates. Code changes made locally and tested with tos serve trigger automatic builds when pushed to the repository. New versions become available for deployment immediately after successful builds.

Version Management

Studio provides version control:

• View all published versions
• Deploy specific versions to different device groups
• Rollback to previous versions instantly
• Compare versions and changes

Instance Configuration

Each application instance on a playlist supports unique settings. Selecting an application in the Studio page editor loads the settings component in the side panel. Instance-specific settings save to instance storage, allowing different playlist instances to maintain different configurations.

Example: The same weather application displays different cities on different screens.

Application Types

Standard Applications

Most applications use the render + settings pattern:

• Render displays content on devices
• Settings provides configuration UI in Studio
• Communicate via Storage API

Example structure:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

Worker Applications

Applications needing continuous background processing:

• Render displays content
• Settings provides configuration
• Worker runs continuously in background

Example use case: Data sync every 5 minutes, even when render not visible.

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings",
    "background": "/worker"
  }
}

Container Applications

Applications needing backend services:

• Render displays content
• Settings provides configuration
• Containers run Docker services on device

Example use case: Local database or API server on device.

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  },
  "containers": [
    {
      "name": "api-server",
      "image": "myapp/api:latest",
      "port": 3000
    }
  ]
}

Common Definition Patterns

Development → Staging → Production

Use branches for different environments:

1. Development - develop branch, auto-deploy to test devices
2. Staging - staging branch, QA testing before production
3. Production - main branch, deployed to production devices

Define three separate applications in Studio, each connected to different branch.

Monorepo with Multiple Applications

Single repository containing multiple applications:

monorepo/
├── apps/
│   ├── weather-dashboard/
│   ├── news-feed/
│   └── social-wall/
└── shared/

Define each application separately in Studio, pointing to same repository but different subdirectories.

Template-Based Applications

Base template applications support forking for customization. Template applications with generic functionality can be forked per customer or location, customized with specific branding and content, and defined as separate applications in Studio.

Security Considerations

Repository Access

Public repositories:

• No authentication required
• Code visible to anyone
• Suitable for open-source applications

Private repositories:

• Requires authentication (OAuth for GitHub, credentials for Git)
• Code remains private
• Recommended for proprietary applications

Build Security

TelemetryOS build process:

• Runs in isolated container
• No access to other customer code
• Secrets/environment variables encrypted at rest
• Build artifacts stored securely

Secrets Management

Never commit secrets to repository:

# ❌ DON'T DO THIS
const API_KEY = 'sk_live_abc123xyz';

Instead, use environment variables configured in Studio:

# ✅ DO THIS
const API_KEY = process.env.API_KEY;

Configure environment variables in Studio application settings.

Troubleshooting

Build Fails

Check build logs in Studio:

• Dependency installation errors
• TypeScript compilation errors
• Build command failures
• Missing files or configuration

Common fixes:

• Ensure package.json scripts are correct
• Verify telemetry.config.json is valid
• Check that build outputs to correct directory
• Ensure all dependencies are in package.json

Application Not Loading

Verify mount points:

• Check telemetry.config.json mount point paths
• Ensure built files exist at specified paths
• Verify HTML files have correct structure

Check browser console:

• SDK configuration errors
• JavaScript runtime errors
• Network request failures

Settings Not Appearing

Verify settings mount point:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"  // ← Must be defined
  }
}

Check settings component:

• Calls configure() with correct app name
• Renders without errors
• Storage API calls are correct

Best Practices

1. Use Git-Based Deployment

Git integration provides the best development experience:

• Version control out of the box
• Automatic builds on push
• Easy rollback and version management
• Team collaboration support

2. Test Before Defining

Always test locally before defining in Studio:

tos serve  # Test locally first

3. Use Semantic Versioning

Follow semantic versioning for clarity:

• 1.0.0 - Initial release
• 1.1.0 - New features, backward compatible
• 2.0.0 - Breaking changes

4. Document Configuration

Add README to repository explaining:

• What the application does
• Required settings/configuration
• Environment variables needed
• How to test locally

5. Environment-Based Branches

Use branches for different deployment environments:

• main → Production devices
• staging → Testing devices
• develop → Development devices

6. Monitor Build Times

Optimize build for faster deployments:

• Minimize dependencies
• Use caching where possible
• Optimize asset sizes
• Consider build output size

Next Steps

After defining the application in Studio:

1. Add to Playlist - Deploy to devices
2. Configure Settings - Instance configuration
3. GitHub Integration - Set up automated deployment
4. Storage Methods - Learn data persistence
5. Local Development - Advanced development workflow

Learn More

• Generate New Application - Use CLI to scaffold applications
• GitHub Integration - Detailed GitHub setup
• Git Repositories - Use any Git provider
• Mount Points - Understand application architecture
• Configuration - Complete telemetry.config.json reference