Managing Stacks

<!-- TIER:1 -->

Managing Stacks

A stack is a pointer to your own compute environment where Celigo runs extension code -- the script hooks and connector wrappers that would otherwise run on Celigo's hosted JavaScript runtime. A stack holds the address and credentials of that environment, not the logic. At runtime, when a hook or wrapper is configured to use a stack, Celigo dispatches that function's execution to the stack instead of running it on its own managed runtime.

Concerns when managing stacks:

• Necessity -- most accounts never need a stack; the hosted runtime handles the vast majority of extension logic. A stack is for a real trigger (see the decision matrix).
• Type and config -- server (a self-hosted HTTP endpoint) or lambda (an AWS Lambda function), each with its own config block.
• Credentials -- a server carries an auto-generated systemToken; a lambda carries AWS keys. Both are masked in responses and demand credential discipline.
• References -- a stack does nothing on its own. It matters only once a hook (via _stackId on an export/import) or a wrapper connection (via _stackId) points at it.

Stacks are a resource type in their own right. They are referenced by script hooks and by wrapper connections.

The Stack Is the Runtime, Not the Code

The distinction the whole domain hangs on:

• The code is the logic: a hook (a JavaScript function on an export/import -- preMap, postSubmit, etc.) or a connector wrapper (the server-side JavaScript that implements a custom adaptor). Hook logic is a script resource; wrapper logic belongs to the wrapper connection.
• The stack is where that code runs. A hook or wrapper points at a stack via _stackId. When set, Celigo dispatches that function's execution to the stack instead of its managed runtime.

So "edit what the hook does" is script work; "change where the hook runs" (managed runtime <-> a stack, or one stack <-> another) is what touches _stackId. A stack is bring-your-own-compute: it supplies the environment, not the behavior.

Stack vs On-Premise Agent

Both put "your own infrastructure" in the loop, but for opposite reasons -- keep the boundary straight:

• A stack is about compute -- running your extension code (hooks/wrappers) on your server or Lambda.
• An on-premise agent is about connectivity -- a tunnel that lets Celigo reach private apps or networks behind your firewall (a database or app with no public endpoint).

"Run our code" -> stack. "Reach our private system" -> on-premise agent. A single flow can use both: an agent to reach a private database, and a stack to run a custom hook.

Quick Reference

Do You Need a Stack?

Default: no. Celigo's hosted JavaScript runtime runs hooks out of the box. Reach for a stack only on a real trigger:

server vs lambda

Neither is "better" -- it's a fit question based on where the team already runs infrastructure.

Minimum Required Fields

Every stack needs name and type. framework is twoDotZero (the only supported version). The rest depends on type:

• awsRegion is an enum (e.g. us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ...).
• functionName accepts a Lambda function name or full ARN.
• Both secrets (systemToken, secretAccessKey) are masked as ****** in responses.

Referencing a Stack (_stackId)

A stack is inert until something points at it:

• Hooks -- an export/import hook definition carries an optional _stackId alongside its _scriptId and function. Set it to dispatch that hook to the stack.
• Wrapper connections -- a wrapper-type connection sets _stackId to the stack whose server-side JavaScript implements the connection. Required by the connection form for standalone wrappers.

To confirm what actually runs on a stack, list its dependents (GET /v1/stacks/{id}/dependencies) -- the hooks and wrapper connections pointing at it.

Related Skills

• configuring-connections > Connection Types -- wrapper connections whose custom-connector code runs on a stack referenced by _stackId
• writing-scripts > How to Write a Script -- the hook logic dispatched to a stack; a hook points at one via _stackId
• managing-on-premise-agents -- the connectivity counterpart: a stack runs your code, an on-premise agent reaches your private systems
• getting-started > Core Concepts -- where stacks fit among the core resource types

<!-- TIER:2 -->

How to Manage a Stack

1. Confirm you actually need one

Use the Do You Need a Stack? matrix. When a user asks "should I set up a stack for this hook," the honest first answer is usually "probably not -- the managed runtime handles it," then escalate only if heavier/specialized code, a compliance requirement, or a custom connector wrapper is genuinely in play. If the real need is reaching a private system, that's an on-premise agent, not a stack.

2. Choose the type

Use the server vs lambda matrix. Pick by where the team already runs infrastructure and how they want to operate it.

3. Check for existing stacks

Before creating a new one, look for a stack you can reuse:

celigo stacks list
celigo account search "stack"
celigo account search "<keyword related to the extension>"

4. Create the stack

Data blocks differ by type. Create the metadata; the runtime code is deployed and owned separately.

# server stack -- systemToken is auto-generated, do not include it
echo '{"name":"Order Enrichment Server","type":"server","framework":"twoDotZero","server":{"hostURI":"https://ext.example.com"}}' | celigo stacks create

# server stack with an IP allow-list
echo '{"name":"Order Enrichment Server","type":"server","framework":"twoDotZero","server":{"hostURI":"https://ext.example.com","ipRanges":["203.0.113.0/24"]}}' | celigo stacks create

# lambda stack -- enter the AWS secret via a local, untracked file; never paste real secrets into chat
celigo stacks create < lambda-stack.json

Example lambda-stack.json (use a placeholder here and supply the real key only in a local file or the UI):

{
  "name": "Order Enrichment Lambda",
  "type": "lambda",
  "framework": "twoDotZero",
  "lambda": {