Documentation by ClonePartner

Start typing to search.

Deployment

Seed import

View Markdown

Understand startup imports of bundled tasks, job templates, and AI references, their create-only semantics, and upgrade planning.

Seed import

At startup, the Envoy server imports authored task and job-template definitions from its configured directories, and customer builds can seed curated AI references. Seeds initialize definitions shipped with a deployment; they are not database backups.

Use seed files for definitions delivered with the image or binary. Use NDJSON bundles for explicit promotion and review between running environments.

What is imported

The startup importer (src/server/importer.ts) processes:

  • task YAML from tasks_dir (default ./tasks);
  • job-template YAML from jobs_dir (default ./jobs);
  • AI reference Markdown from the image's seed directory, filtered by ENVOY_CUSTOMER when set.

Connector credentials, instantiated Jobs, connector bindings, job configuration values, runs, logs, users, sessions, and API keys are never seed content.

Startup behavior

Import is create-only. For each YAML file the importer:

  1. reads and parses the file; parse failures are logged ([importer] Failed to parse YAML <path>, skipping) and skipped;
  2. takes the name from the YAML's name: field; files without a name are skipped with [importer] Skipping <path>: missing or empty 'name' field;
  3. skips the file when a record with that name already exists in the database;
  4. otherwise creates the record (tasks get a version 1 with change summary Imported from file system).

Existing database records are therefore never overwritten by changed bundled files — after the first import, the database copy is authoritative and edits made in the UI survive restarts and image upgrades. To push updated definitions into an existing deployment, use a bundle import, which supports upsert modes.

Two environment variables control the import (read in src/server/index.ts):

  • ENVOY_SKIP_SEED_IMPORT=true — skip task, job, and AI-reference import entirely;
  • ENVOY_CUSTOMER — restrict seed content to one customer's slug.

Importer messages go to server stderr. Treat importer errors as deployment failures to investigate; a running process does not prove every intended definition imported.

Relationship to bundle import

The bundle API (src/server/api/export-import.ts) is the explicit alternative with real conflict handling. Its import modes are create_only, upsert_current, and upsert_all_versions; conflict policies are skip, overwrite, and error; archived-task policies are skip, restore, and keep_archived; and dry_run previews the outcome. The startup seed import is equivalent to a permanent create_only pass — anything more nuanced belongs in a bundle workflow. See Bundles: export and import.

Prepare an upgrade

  1. Read the release notes and schema changes.
  2. Back up the application database and required external state.
  3. Preserve the current executable, configuration, and catalog assets.
  4. Export authored Tasks and Job Templates as an additional review artifact.
  5. Validate new seed definitions against the target build.
  6. Confirm required connector types exist in the new build.
  7. Test the upgrade against a copy of representative state.

Never test an irreversible migration first against the only production database.

Deploy consistently

All control-plane replicas should use the same executable version, schema version, seed content, connector catalog, branding assets, and environment configuration. During a rolling upgrade, prevent incompatible versions from concurrently mutating the same state unless that pattern is explicitly supported.

Verify after upgrade

Check server readiness, startup import summaries and errors in stderr, task and job-template versions, connector type availability, scheduled Triggers, and one bounded Task and Job run. Existing Jobs retain snapshotted task and template content — upgrade a Job only after reviewing the resolved diff.

Rollback

An executable rollback may not reverse a database schema migration. Follow the release-specific rollback procedure and restore from a verified backup when required. Do not delete volumes or application databases to force re-seeding — that destroys operational state and is not an upgrade mechanism.