Chapter 1: Connect the demo worker and build your first topology

Welcome to the Orchesty onboarding series. Across these chapters you'll work with the demo worker (a ready-made project full of small, self-contained examples) and pick up the core platform skills hands-on. This is the fastest way to go from zero to a running, inspectable integration.

By the end of this chapter you'll be able to:

• Run the demo worker locally and connect it to your platform over a tunnel.
• Find your way around the project's src/ folder.
• Build a topology by hand in the editor (you won't import it) and, optionally, use a breakpoint to see what your data looks like mid-flow.

Prerequisites #

• An Orchesty platform you can log into (a trial instance is fine).
• Node.js 20+ or Docker, and git.

New to workers in general? Build your first worker covers the bigger picture. This series instead uses the pre-built demo worker so you can focus on the platform.

1. Get the demo worker running #

Clone the repository and let the Makefile do the setup:

git clone https://github.com/Orchesty/orchesty-demo-worker.git
cd orchesty-demo-worker
make init-dev

make init-dev installs dependencies, generates a .env from the bundled template, and starts the dev server. Leave it running. You'll point it at your platform next.

2. Find your way around src/ #

Everything you'll touch lives under src/. The layout follows one simple rule: each demo gets its own folder, and all topology definitions live together in topologies/.

src/
  index.ts            # entry point: registers every application and node with the platform
  AddTimestamp/       # the custom node used in this chapter (add-timestamp)
  ProductsTest/       # simulated product catalog: connector and batch demos (next chapters)
  WebhookTest/        # webhook-with-registration demo
  FormsDemo/          # custom settings forms + mapper demo
  topologies/         # all topology files (*.tplg.json), one per demo

A few things worth knowing as you explore:

• index.ts is where components become visible to the platform. Anything registered here shows up in the topology editor once the worker is connected.
• Each demo folder is independent; you can read one without needing the others.
• The topologies/ folder holds the finished topology definitions. In this chapter you'll build demo-timestamp yourself instead of importing the file, so you actually learn the editor.

3. Connect the worker over a tunnel #

A tunnel lets the worker reach your platform without exposing anything publicly, which is ideal for local development. In the Admin UI you add a Tunnel worker, and the registration dialog hands you an environment block to paste into the worker's .env. After a restart, the worker shows as connected and every node from src/index.ts (including add-timestamp) becomes available in the topology editor.

4. Build the demo-timestamp topology yourself #

This topology is tiny (an Event trigger into the add-timestamp custom node), but you'll wire it by hand so you learn the editor instead of importing a finished file.

The shape you're building:

[ Event ] → [ add-timestamp ]  ( → [ Breakpoint ] optional )

In the editor you'll create a new topology named demo-timestamp, then drop and connect an Event trigger and a Custom Action set to add-timestamp. Optionally add a Breakpoint at the end (see the next step). Then Publish and Enable it.

Two things worth calling out while you build:

• The trigger's on-canvas label is "Event"; that's the element type. Its name is separate and can be anything; we often use start, but it doesn't change the label.
• The Breakpoint is optional. Add it at the very end if you want to pause and inspect the message after add-timestamp runs; if you don't need it, leave it out and the topology works exactly the same.

5. Run it and inspect the result #

Trigger a run from the Event node and (optionally) paste a small JSON payload, e.g. { "order": 123 }. If you added a Breakpoint, the process pauses there and shows the in-flight message, so you'll see your payload plus the receivedAt field that add-timestamp added. Either way, the Processes tab on the topology detail confirms the run and shows which nodes were visited, so you can inspect the result there too.

Where next #

In Chapter 2 you'll build the demo-get-product topology, which calls a real HTTP endpoint. To make that work you'll start the bundled mock server (introduced there) and install your first application to handle the connection.