Deployment

The informer-deploy command builds your project and uploads it to Informer in a single step.

Quick Start

npm run deploy

This runs npm run build followed by informer-deploy, which handles the entire deployment pipeline.

Deploying to Different Environments

Use --mode to target a specific Informer server. The command loads .env.<mode> for connection settings (see Environment Variables):

# Deploy to test server (loads .env.test)
npm run deploy -- --mode test

# Deploy to production (loads .env.production)
npm run deploy -- --mode production

What Happens During Deploy

The deploy command executes these steps in order:

1. Find or Create the App

The command looks up your app by the UUID stored in package.json (informer.id). It tries the /api/apps endpoint first, falling back to the legacy /api/reports endpoint for older servers.

If no app exists yet (first deploy), it creates one and saves the UUID to package.json for future deploys.

2. Update Metadata

If the app name, description, or icon in package.json differs from the server, the command updates them.

3. Create Snapshot

Takes a snapshot of the app's current library contents. This provides a rollback point — you can restore the previous version from the Informer UI if something goes wrong.

4. Clear Existing Files

Removes all files from the app's library. This ensures the deployed version is a clean copy of your dist/ directory, with no leftover files from previous deploys.

5. Upload Built Assets

Uploads all files from dist/ to the app's library:

• Text files (.html, .css, .js, .json, .svg, .md, .yaml, etc.) are uploaded as UTF-8
• Binary files (images, fonts, etc.) are uploaded as Base64
• Large files (>512KB) use chunked upload via the Flow.js protocol

6. Upload Config Files

Uploads informer.yaml (and data-access.yaml for backwards compatibility) from the project root, if they exist.

7. Upload Migrations

Uploads all files from migrations/ to the app's library, preserving the directory structure.

8. Upload Server Handlers and Webhooks

Uploads all files from server/ (authenticated routes) and webhooks/ (public routes) to the app's library.

9. Upload Tools

Uploads all files from tools/ to the app's library. Tools are JavaScript files that agents can call during execution.

10. Run Deploy

Calls POST /api/apps/{id}/_deploy, which runs the full deploy pipeline:

1. Migrations — runs any pending SQL migrations against the app's workspace
2. Route scanning — discovers handler files in server/ and webhooks/
3. Handler bundling — bundles all handlers with esbuild
4. Route table — registers routes in the database
5. Widget extraction — parses widget definitions from informer.yaml
6. Resource resolution — resolves dataset, query, datasource, integration, and toolkit references from informer.yaml into junction tables (fails with 400 if any referenced resource doesn't exist)
7. Tool scanning — discovers and bundles tool files from tools/
8. Agent extraction — creates/updates agent records from informer.yaml, stops agents removed from config

11. Print URL

Prints the app's URL and the total number of files uploaded.

Configuration

package.json

{
    "informer": {
        "name": "Sales Dashboard",
        "description": "Regional sales overview",
        "id": "a1b2c3d4-5678-90ab-cdef-123456789abc"
    }
}

Field	Description
name	Display name in Informer (falls back to package name)
description	App description (optional)
id	App UUID — auto-generated and saved after first deploy

.env

The deploy command reads connection settings from .env:

INFORMER_URL=http://localhost:3000
INFORMER_API_KEY=your-api-key

Or with basic auth:

INFORMER_URL=http://localhost:3000
INFORMER_USER=admin
INFORMER_PASS=yourpassword

CI/CD

The deploy command works in non-interactive environments. Set environment variables instead of using a .env file:

export INFORMER_URL=https://informer.example.com
export INFORMER_API_KEY=$INFORMER_API_KEY
npm run deploy

GitHub Actions Example

name: Deploy App
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run deploy
        env:
          INFORMER_URL: ${{ secrets.INFORMER_URL }}
          INFORMER_API_KEY: ${{ secrets.INFORMER_API_KEY }}

GitLab CI Example

deploy:
  stage: deploy
  image: node:20
  script:
    - npm ci
    - npm run deploy
  variables:
    INFORMER_URL: $INFORMER_URL
    INFORMER_API_KEY: $INFORMER_API_KEY
  only:
    - main

Rollback

If a deploy introduces issues, you can restore the previous version from the Informer UI:

1. Open the app in the admin panel
2. Navigate to the library's snapshot history
3. Restore the snapshot created before the last deploy

The deploy command creates a snapshot automatically before uploading, so there's always a rollback point.

Legacy Server Support

The deploy command automatically detects whether your Informer server supports the new /api/apps endpoint or only the legacy /api/reports endpoint. It tries the new API first and falls back transparently. You don't need to configure anything — it just works.