Tutorial Deploying First Pod

Tutorial: Deploying Your First Pod

This tutorial walks you through deploying your first pod from scratch, explaining each step along the way.

Prerequisites

• Stark Orchestrator installed and running (see Installation)
• CLI built and accessible
• An admin account created

Overview

We'll accomplish the following:

1. Start a node agent
2. Create and bundle a simple pack
3. Register the pack
4. Deploy a pod
5. Verify it's running

Step 1: Login

First, ensure you're logged in:

node packages/cli/dist/index.js auth login --email your@email.com

Verify with:

node packages/cli/dist/index.js auth whoami

Step 2: Start a Node Agent

Open a new terminal and start a node agent:

node packages/cli/dist/index.js node agent start \
  --url wss://localhost/ws \
  --name tutorial-node \
  --label env=tutorial \
  --cpu 1000 \
  --memory 512

Keep this terminal running. The node is now connected and waiting for pods.

Verify the Node

In your original terminal:

node packages/cli/dist/index.js node list

You should see tutorial-node listed with status Ready.

Step 3: Create a Simple Pack

Create a file called hello-pod.js:

// hello-pod.js
console.log('=================================');
console.log('  Hello from Stark Pod!');
console.log('  Running at:', new Date().toISOString());
console.log('=================================');

Step 4: Bundle the Pack

node packages/cli/dist/index.js pack bundle ./hello-pod.js --out ./hello-bundle.js

This creates a self-contained bundle ready for service.

Step 5: Register the Pack

node packages/cli/dist/index.js pack register ./hello-bundle.js \
  --name hello-pod \
  --ver 1.0.0 \
  --runtime node

Verify registration:

node packages/cli/dist/index.js pack list

Step 6: Create the Pod

Now for the exciting part—deploy the pod:

node packages/cli/dist/index.js pod create \
  --pack hello-pod \
  --node tutorial-node

This will return a pod ID like pod-abc123.

Step 7: Check Pod Status

node packages/cli/dist/index.js pod list

You should see your pod with status Running or Succeeded.

For detailed status:

node packages/cli/dist/index.js pod status <pod-id>

Step 8: View the Output

Check the node agent terminal. You should see:

=================================
  Hello from Stark Pod!
  Running at: 2026-02-02T10:30:00.000Z
=================================

🎉 Congratulations! You've deployed your first pod!

What Happened Behind the Scenes

1. Pack Registration: Your JavaScript code was stored in the pack registry with version 1.0.0
2. Pod Creation: You requested a pod running hello-pod on tutorial-node
3. Scheduling: The scheduler verified tutorial-node was available and had sufficient resources
4. Assignment: The orchestrator sent a pod assignment to the node via WebSocket
5. Execution: The node agent executed your pack code
6. Status Update: The node reported the pod status back to the orchestrator

Next Steps

Try Deploying with Constraints

node packages/cli/dist/index.js pod create \
  --pack hello-pod \
  --node-selector env=tutorial \
  --priority 200 \
  --label app=hello

Try a Service

For managed pods with auto-healing:

node packages/cli/dist/index.js service create hello-service \
  --pack hello-pod \
  --replicas 2

Update and Rollback

Register a new version and roll back:

# Create updated version
echo 'console.log("Hello v2!")' > hello-pod-v2.js
node packages/cli/dist/index.js pack bundle ./hello-pod-v2.js --out ./hello-v2.js
node packages/cli/dist/index.js pack register ./hello-v2.js --name hello-pod --ver 2.0.0 --runtime node

# Rollback if needed
node packages/cli/dist/index.js pod rollback <pod-id> --ver 1.0.0

Cleanup

# Delete the pod
node packages/cli/dist/index.js pod delete <pod-id>

# Stop the node agent (Ctrl+C in the node terminal)

Troubleshooting

Pod stays in Pending

• Verify the node is online: node list
• Check node labels match selectors
• Verify node has sufficient resources

Pack bundle fails

• Ensure the source file exists and is valid JavaScript
• Check file permissions

Node won't connect

• Verify the orchestrator is running
• Use -k flag for self-signed certificates
• Check the WebSocket URL is correct

Related Topics

• Tutorial: Writing a Pack
• Scheduling Policies
• CLI Reference