Get started

This walkthrough deploys a Node.js app from scratch using nothing but curl. Every write operation is async. You get back a job or deployment id and poll until it is ready.

Prerequisites

• A Personal Access Token with the following scopes: hosting.paas.apps:create, hosting.paas.apps:read, hosting.paas.code:write, hosting.paas.deploy:execute.
• A zipped Node.js application. The zip's root should contain your package.json and application entry point.
• curl and jq (or your language's HTTP client — the flow is the same shape everywhere).

1. Get a token

Create a Personal Access Token (PAT) at Personal Access Tokens with the scopes listed in Prerequisites, then set it as an environment variable:

export TOKEN="gd_pat_your_token_here"

See Authentication for the full PAT creation steps.

2. Create an app

POST /apps accepts a name and returns 202 with a job id. The app isn't ready to receive code until the job reaches active.

JOB=$(curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-first-app" }')

JOB_ID=$(echo "$JOB" | jq -r .job.id)
echo "Job accepted: $JOB_ID"

Poll GET /apps/jobs/{jobId} until job.status is active. When it flips, the response also includes the fully-formed app object.

until STATUS=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/jobs/$JOB_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r .job.status) && [ "$STATUS" = "active" ]; do
  echo "  ...still $STATUS"
  sleep 3
done

APP_ID=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .app.id)
echo "App ready: $APP_ID"

Terminal states are active (success) and failed (fatal — start over with a corrected request).

3. Upload your source

Package the app as a zip, then POST /apps/{appId}/source as multipart/form-data. This lands on the preview variant.

UPLOAD=$(curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/source" \
  -H "Authorization: Bearer $TOKEN" \
  -F "zipFile=@./my-app.zip")

UPLOAD_JOB=$(echo "$UPLOAD" | jq -r .jobId)

Poll the upload job at GET /apps/{appId}/source/status?jobId=... until it terminates.

until echo "$RESP" | jq -e '.status | test("succeeded|failed")' >/dev/null 2>&1; do
  RESP=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/source/status?jobId=$UPLOAD_JOB" \
    -H "Authorization: Bearer $TOKEN")
  echo "  upload: $(echo "$RESP" | jq -r .status)"
  sleep 2
done

4. Publish

Publishing takes the current preview source and promotes it to the publish variant. POST /apps/{appId}/deployments returns a deployment record. Poll the deployments list and app status to observe rollout.

curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/deployments" \
  -H "Authorization: Bearer $TOKEN"

Watch runtime status flip to running on the publish variant:

until curl -s "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/status" \
    -H "Authorization: Bearer $TOKEN" \
  | jq -e '.variants[] | select(.variant == "publish") | .status == "running"' >/dev/null; do
  echo "  ...deploying"
  sleep 5
done

echo "Live."

Last updated on