Skip to main content
Nelkap runs your workflows in your own app, so deploying them means deploying your app, the way you already do. There’s no separate worker to run and no build step to add. Your app needs three things in production: the SDK’s keys, a route Nelkap can reach, and the list of workflows it runs.

​
Before your first deploy

  1. Set your project’s endpoint to the URL the route will have, like https://your-app.com/api/nelkap.
  2. Set NELKAP_API_KEY and NELKAP_SECRET in your host’s environment variables. See Installation.
  3. Deploy. When your app starts, registerWorkflows sends its list of workflows to Nelkap.
Then start a run, and open it from your runs to follow each step.

​
What your endpoint needs

Nelkap calls your endpoint over the internet, from its own servers. The URL must:
  • Use HTTPS, on a domain name. An IP address or localhost isn’t accepted.
  • Be public. A route behind a sign-in, a VPN, or a firewall that blocks Nelkap can’t be reached.
  • Answer within 30 seconds, without a redirect. handle answers at once, so this only matters if something runs before it.
If your app checks sign-in on every route, for example in a middleware, leave this one out. handle checks your project’s secret instead.

​
How Nelkap calls your app

Each time a run has work to do, Nelkap sends a POST request to your endpoint:
  • The Authorization header carries your project’s secret, as Bearer <secret>. handle answers 401 if it doesn’t match NELKAP_SECRET.
  • The JSON body names the workflow, and carries the run’s ID, its payload, and the steps already saved.
handle answers 202 at once, then runs the workflow in the background. While the workflow runs, the SDK saves each step as it finishes, and tells Nelkap every minute that the run is still going. If your endpoint doesn’t answer with a 2xx status, or can’t be reached, Nelkap tries again about a minute and a half later. After three attempts, the run fails with deliveryFailed. Once your endpoint is back, replay the run.

​
Register your workflows on every start

registerWorkflows runs each time your app starts, and sends the full list of workflows to Nelkap. The list replaces the one Nelkap had:
  • New workflows are added.
  • Workflows you changed take their new events, schedule, and concurrency.
  • Workflows you removed are turned off, and their runs that haven’t started, or are sleeping or waiting, are canceled.
On a serverless host, your app starts with the first request it gets after a deploy, not when the deploy ends. Until then, Nelkap keeps the list from before. run and emit make sure the list is sent before their own request, so what you start from your code is never affected. A change that must apply before then, like a new schedule, waits for that first request: start a run or emit an event from the new deploy to send the list right away. Every instance of your app must register the same list. A project has one endpoint, so all its workflows run in one app: give each app its own project. See Workspaces and projects.

​
Runs during a deploy

A deploy can stop your app in the middle of a run. Nothing is lost:
  • Runs that are sleeping, waiting, or waiting for their turn aren’t running anywhere, so the deploy doesn’t touch them.
  • A run cut off in the middle of a call stops sending its signal. About five minutes later, Nelkap calls your app again, now on the new version, and the run picks up from its last saved step.
  • A step cut off before its result was saved runs again from its start. See When a step can run twice.
Every run that goes on after the deploy uses your new code. See Change a workflow safely.

​
Time limits

Nelkap puts no limit on how long a call takes. Your host might. On serverless hosts, a function stops after a set time, and some stop as soon as the response is sent:
  • Pass your host’s waitUntil to handle, so the work goes on after the response. Each framework page shows the right one.
  • When the host cuts a call off at its limit, the steps already saved are kept, and Nelkap calls your app again about five minutes later to go on from there.
  • Keep each step shorter than your host’s limit. A single step longer than the limit can never finish.
On a server that keeps running, like a container or a virtual machine, there’s no limit to plan for.

​
Rotate your project’s secret

If your secret leaks, rotate it from your project. Your endpoint then turns every call away until it has the new one, so update NELKAP_SECRET and deploy right after. Calls in the meantime are tried again, up to three attempts in about three minutes. A run whose three attempts all fail shows deliveryFailed: replay it once the new secret is live.