Using Fixtures to Seed Uptrace Data

Data fixtures let you create and manage users, organizations, and projects in a self-hosted Uptrace from the seed_data section of the config file. The uptrace db seed command applies them. You can run it again with the same file: it updates the rows it created and does not make duplicates. This makes fixtures safe to use in CI/CD pipelines and multi-environment setups.

The key system

Each resource has a key field — a stable, user-defined identifier. Uptrace uses it to:

• Track resources across multiple seed runs
• Update existing resources instead of creating duplicates
• Establish references between resource types (e.g. a project references an org by org_key)

Keys are case-sensitive and must be unique within each resource type. Uptrace stores the keys in the database, so a later run finds the rows that an earlier run created.

Supported resources

Configuration

Define fixtures in the seed_data section of uptrace.yml:

seed_data:
  # Update a resource whose key already exists.
  update: true
  # Delete a resource whose key this section no longer declares.
  delete: true

  users:
    - key: admin_user
      name: System Administrator
      email: admin@company.com
      email_confirmed: true
      password: change_me_immediately

  user_tokens:
    - key: admin_token
      user_key: admin_user
      token: admin_api_token

  orgs:
    - key: main_org
      name: Acme Corporation

  org_users:
    - key: admin_membership
      org_key: main_org
      user_key: admin_user
      role: owner

  projects:
    - key: web_app_project
      name: Web Application
      org_key: main_org
    - key: api_project
      name: REST API
      org_key: main_org

  project_tokens:
    - key: web_app_token
      project_key: web_app_project
      token: web_app_secret

  project_users:
    - key: admin_web_app
      project_key: web_app_project
      org_user_key: admin_membership
      perm_level: admin

Uptrace rejects a key it does not know under seed_data, so a typo fails the seed instead of being ignored.

Applying fixtures

Run uptrace db seed after uptrace migrate up:

uptrace --config=/etc/uptrace/config.yml migrate up
uptrace --config=/etc/uptrace/config.yml db seed

The Ansible role and the Helm chart run both commands for you on each deploy.

The command applies the whole section in one transaction:

• A key that is new creates a resource.
• A key that an earlier run created updates that resource.
• With delete: true, a key that an earlier run created and that the section no longer declares deletes its resource.

After a reset of the PostgreSQL database, run uptrace db seed again to create the resources again.

Roles and permissions

Organization roles (org_users.role): owner, admin, member, viewer, collaborator, billing_manager

Project permission levels (project_users.perm_level): admin, edit, view, none

Example: multi-environment setup

seed_data:
  update: true
  delete: true

  orgs:
    - key: company_prod
      name: Production
    - key: company_staging
      name: Staging

  projects:
    - key: app_prod
      name: Main Application
      org_key: company_prod
    - key: app_staging
      name: Main Application
      org_key: company_staging

Security guidelines

• Never commit passwords or tokens to version control — keep the config file out of the repository, or fill these values from your secret store when you deploy
• Change seeded passwords immediately after the first login
• Give a CI/CD token only the permissions it needs
• Rotate tokens regularly, especially in production environments

Related

• Observability as Code — Terraform-based management of monitors, channels, and projects
• SSO — manage user access through an identity provider instead of manual fixtures