jhub-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# JHub Arbitrary Deploy Skill

Use this skill when the user wants agents to:
- build arbitrary frontend/backend apps,
- deploy them through JupyterHub,
- manage lifecycle (status/stop/delete) via Hub API directly,
- avoid framework-specific preference and avoid mandatory image push.

This skill piggybacks on **JupyterHub named servers**.

---

## 1) Preconditions

Resolve Hub API context from runtime:

```bash
API_URL="${NEBARI_HUB_API_URL:-${JUPYTERHUB_API_URL:-}}"
API_TOKEN="${NEBARI_HUB_API_TOKEN:-${JUPYTERHUB_API_TOKEN:-}}"
HUB_USER="${JUPYTERHUB_USER:-${NB_USER:-}}"

[ -n "$API_URL" ] || echo "Missing API_URL"
[ -n "$API_TOKEN" ] || echo "Missing API_TOKEN"
[ -n "$HUB_USER" ] || echo "Missing HUB_USER"
```

Validate token can read own user:

```bash
curl -fsS -H "Authorization: token $API_TOKEN" \
  "$API_URL/users/$HUB_USER?include_stopped_servers=true" >/dev/null
```

If this fails, stop and report missing scopes/credentials.

### 1.1) Runtime dependency preflight (MUST run)

Before selecting command/image strategy, verify required runtime dependencies for the target app.

Examples:
- shell-out binaries (`pdftotext`, `ffmpeg`, etc.)
- language runtimes/toolchains
- expected package managers/build tools

If required binaries are missing in target image/runtime:
- either switch to image mode,
- or include bootstrap installation/fallback logic explicitly,
- or fail fast with clear remediation.

---

## 2) Deployment modes (default = no image push)

### A) **Source-on-home mode** (conditional, not assumed)
- Build/install app on user home/workspace (`/home/jovyan/...`)
- Spawn named server to run command from that path
- **No image push required**

**Critical rule:** use source-on-home mode only if shared storage between build context and target named server is confirmed.

### B) **Bootstrap-on-target mode** (safe default when storage is uncertain)
- Treat target named server as isolated storage
- Build/write artifacts inside target server startup flow
- Prefer Python bootstrap wrapper that prepares files then `exec`s runtime

### C) Image mode (optional)
- Use custom image when runtime deps cannot be satisfied in source/bootstrap modes
- Can use local cluster image import for local k3d/k3s
- Registry push is optional, only needed when cluster cannot access local image

Do not prefer framework-native templates. Treat all apps as arbitrary command-based runtimes.

### 2.1) Storage topology preflight (MUST run)

Before using source-on-home mode, verify whether target named server shares storage with where artifacts were built.

Minimum checks:
1. If target server already exists, inspect/compare PVC claim identity with current runtime server.
2. If target server does not exist yet, treat storage as **unknown** and do **not** assume shared home.
3. If unknown or different, require bootstrap-on-target or image mode.

Failure message should explicitly say source-on-home was rejected due to non-shared/unknown storage topology.

### 2.2) Image resolution preflight (MUST run when `profile_image` is empty)

`profile_image: ""` can resolve to a broken default image.

Required behavior:
1. Resolve a known-good image before spawn when `profile_image` is empty.
2. Resolution order:
   - `JUPYTER_IMAGE_SPEC` from current runtime, else
   - image from a currently ready server for same user, else
   - explicit configured fallback image.
3. If spawn fails with pull errors (`ImagePullBackOff`/`ErrImagePull`), retry once with resolved known-good image.

---

## 3) App spawn contract

Assume deployment supports a command-based `user_options` contract for named servers.
Preferred payload shape:

```json
{
  "profile": "<optional-profile>",
  "app": {
    "cwd": "/home/jovyan/apps/myapp",
    "command": "<runtime command with {port} placeholder>",
    "env": {"KEY": "VALUE"}
  },
  "profile_image": "<optional-image>"
}
```

If your Hub uses a different key shape, adapt payload to the deployment’s configured spawner hooks.

### 3.1) Default resilient command pattern (REQUIRED)

To avoid brittle spawn failures, default to this pattern:

From nebari-dev/pi-coding-agent-pack, Apache-2.0.

More from nebari-dev/pi-coding-agent-pack