Getting started

Set up a small Smeltr deployment.

Use the leader's browser interface to build, test, and deploy configuration. Workers run that configuration and move records from sources to destinations.

How Smeltr fits together

How Smeltr fits togetherAn administrator edits and reviews configuration on the leader. The leader stores it in Git. Workers fetch main and report their status to the leader. Source records flow through workers to destinations. The stacked worker cards represent one or more workers.Fetch mainReport statusAdministratorEdit · test · reviewLeaderUI + Git repositorySourcesInput recordsWorkersFilter and deliver recordsDestinationsKept recordsHow Smeltr fits togetherAn administrator edits and reviews configuration on the leader. The leader stores it in Git. Workers fetch main and report their status to the leader. Source records flow through workers to destinations. The stacked worker cards represent one or more workers.AdministratorEdit · test · reviewLeaderUI + Git repositorySourcesInput recordsWorkersFilter and deliver recordsDestinationsKept records
The leader provides the editing and review screens and stores configuration in Git. Workers fetch main and report their status. Workers also connect directly to sources and destinations, where they read, filter, and deliver records. Dashed arrows show workers fetching configuration and reporting status. The stack represents one or more workers.

A worker group is a set of workers that run the same group configuration. Groups let you manage different environments separately while sharing reusable pipelines. Read how workers follow main →

What you need

  • A Smeltr binary, or the container image from ghcr.io/smeltr-sh/smeltr, with its version and checksum or digest.
  • One host for a standalone process, or a leader host and separate worker hosts for a distributed deployment.
  • Each separate worker can reach the leader over the network.
  • Git installed on the leader host to serve the configuration repository. Workers use a built-in Git client. See Repository hosting.
  • Access to the sources and destinations your configuration will use.

The leader trusts every enrolled worker with the whole cluster's configuration and leader-stored credentials. Groups do not restrict that access. Use separate clusters when workloads require separate trust boundaries.

Connect your data systems

Choose a source to read, a pipeline to shape the records, and a destination to receive them. Workers make these connections, so check network access and credentials from the worker hosts. Use the connector options and release notes supplied with your version.

  • Sources — input types, read positions, authentication, and setup.
  • Destinations — output types, delivery settings, and verification.
  • Secrets & credentials — shared credentials and connection identities.

Choose where to run Smeltr

Standalone: one process

Run the leader and one worker together in a single Smeltr process for evaluation or a small deployment. Enable both leader.enabled and worker.enabled in the same configuration file. For a local test, bind to 127.0.0.1 so only that machine can connect.

Standalone: leader and worker in one processAn administrator connects to the leader. One Smeltr binary runs the leader and one worker together in a single process, shown as joined cards. Sources send records through the worker to destinations.One processAdministratorEdit · test · reviewLeaderUI + Git repositoryWorkerFilter and deliver recordsSourcesInput recordsDestinationsKept recordsStandalone: leader and worker in one processAn administrator connects to the leader. One Smeltr binary runs the leader and one worker together in a single process, shown as joined cards. Sources send records through the worker to destinations.One Smeltr processAdministratorEdit · test · reviewSourcesInput recordsLeaderUI + Git repositoryWorkerFilter and deliver recordsDestinationsKept records
One binary, one process: the leader and one worker run together. The administrator uses the leader; the worker reads from sources, filters records, and delivers them to destinations.

Distributed: separate machines

Run the leader on its own machine and place workers near their sources and destinations. Workers connect to the leader; the leader does not need inbound access to worker hosts.

The leader stores configuration history, accounts, and other installation state on its host. Preserve its data directory across restarts and upgrades, and back it up.

Quick start

  1. Choose your setup: standalone with one built-in worker, or a leader with separate workers. Prepare the account, files and directories in the installation guide before starting.
  2. Sign in with the initial credentials, choose a password, and confirm the default worker group exists.
  3. For standalone mode, the worker enrolls automatically. For separate workers, create an enrollment code and enroll each worker.
  4. Open Status. Wait for the worker to appear Online and compare its running commit with main. An online worker has contacted the leader; its running commit confirms which configuration it loaded.
  5. Use Your first pipeline to build, test, review and deploy a change, then verify a real record at the destination.

Check the installation

Before handing a network deployment over, check each result. The local HTTP evaluation can defer HTTPS until you make it reachable over the network:

  • Trusted HTTPS. Open the leader at its configured address. The browser accepts its certificate. Set up trust.
  • Named administrator access. Sign in with your own account and complete any first-login password change. Create an account.
  • An online worker. Status shows the expected group and a recent heartbeat. Check worker status.
  • The intended configuration is running. Each worker in the test group reports the deployed commit. Check deployment.
  • A record arrives at the destination. Send a fresh record and check its transformed fields where Smeltr delivers it. Verify the data path.
  • A recoverable backup. Take a consistent leader backup, retain the matching sealing key securely, and test a restore in isolation. Follow the backup procedure.

Next steps

Use the operations guide to check workers, deploy changes, and recover from failures. If a check fails, use Troubleshooting to work through the connection, certificate, or deployment error.