How to deploy your Node.js app

View as Markdown

Deploy your app end to end with the gddy CLI or the REST API. Create an app, upload code, attach a hosting plan, publish, and verify it's running.

Overview

This walkthrough deploys an app from scratch. By the end, you'll have a running app on the publish variant. Creating an app, uploading source, and publishing are async. Each call returns an ID immediately, and you poll until the operation reaches COMPLETED.

You can follow the steps with the gddy CLI or with the Hosting REST API. The CLI is the recommended path. It signs you in through your browser and asks you to approve each scope the first time a command needs it. The API path uses a Personal Access Token and shows curl, Node, Python, and Go examples. Those examples use $BASE_URL for the API gateway host and $GODADDY_PAT for the token. Go to Hosting core concepts for the scopes involved.

How do you want to deploy?

Prerequisites for the CLI

The following prerequisites are required before you can deploy your Node.js app:

  • the GoDaddy CLI installed and signed in

    Go to Set up the CLI to install and authenticate gddy.

  • a zipped Node.js application that meets the Node.js app requirements

  • a web hosting subscription with a free app slot, which you need only to publish

Deploy your app with the CLI

The following procedure creates an app, uploads source, attaches it to a hosting plan, publishes it to production, and confirms the app is running.

Create an app with the CLI

gddy hosting app create returns an operationId, which is $OPERATION_ID in the poll command. After the operation reaches COMPLETED, its app.id field is the app ID, which is $APP_ID in every later command.

The following procedure creates the app and polls the operation until provisioning finishes.

  1. Create the app:

    gddy hosting app create --app-type NODEJS --name my-first-app
  2. Poll until the operation reaches COMPLETED or FAILED:

    gddy hosting operation get --operation-id $OPERATION_ID

Upload source and preview your app with the CLI

gddy hosting source upload accepts a zip and returns an importId, which is $IMPORT_ID in the poll command. After the import reaches COMPLETED, your code runs on the preview variant. Preview works without a hosting plan. The preview URL is private, so sign in to your GoDaddy account to open it.

The following procedure zips your app, uploads it, polls the import, and reads the preview URL.

  1. Zip the app, leaving out node_modules, .env files, and .git:

    zip -r my-app.zip . -x "node_modules/*" -x ".env*" -x ".git/*"
  2. Upload the zip:

    gddy hosting source upload --app-id $APP_ID --file ./my-app.zip
  3. Poll until the upload reaches a terminal state:

    gddy hosting source status --app-id $APP_ID --import-id $IMPORT_ID
  4. Read the preview URL:

    gddy hosting app get --app-id $APP_ID --fields urls

Attach to hosting plan with the CLI

Before you can publish a Node.js app, you must attach it to a web hosting subscription. gddy hosting subscription list returns your plans, and each plan has a subscriptionId and an availableSlots count. Use the subscriptionId of a plan with at least one available slot as $SUBSCRIPTION_ID. Go to Attach to a hosting plan for detailed guidance.

The following procedure finds a hosting plan and attaches the app to it.

  1. List your web hosting plans:

    gddy hosting subscription list --hosting-product WEB_HOSTING
  2. Attach the app to a subscription:

    gddy hosting subscription attach --app-id $APP_ID --subscription-id $SUBSCRIPTION_ID

Publish your app with the CLI

gddy hosting deployment publish builds the latest source, deploys it to the publish variant, and returns a deploymentId, which is $DEPLOYMENT_ID in the poll command.

The following procedure publishes the app and polls the deployment until it finishes.

  1. Publish the app:

    gddy hosting deployment publish --app-id $APP_ID
  2. Poll until the deployment reaches a terminal state:

    gddy hosting deployment get --app-id $APP_ID --deployment-id $DEPLOYMENT_ID

Verify with the CLI

gddy hosting app status returns the application lifecycle in status and per-environment detail in variants. The app is healthy when status is ACTIVE. The other values are CREATING, FAILED, DELETING, SUSPENDED, and UNKNOWN. UNKNOWN means the state can't be determined, so don't treat it as healthy. Each entry in variants has its own status, which is ACTIVE when that environment is healthy. It also has a lowercase lifecycleState, which is running when that environment is up. The other main lifecycleState values are provisioning, reloading, paused, deleting, and failed. Other values are possible.

The following procedure confirms the app is running.

  1. Read the app status:

    gddy hosting app status --app-id $APP_ID
  2. Check that status is ACTIVE, and that the PUBLISH entry in variants has a status of ACTIVE and a lifecycleState of running. The CLI nests these fields under data.

  3. Open the urls.publish address to see the live app. The next step shows how to read it.

Get app URLs with the CLI

gddy hosting app get returns the full app record, including a urls object with the URL for each environment. Open urls.publish to see the live app. Your code isn't live there until you publish.

The following procedure reads the publish URL.

  • Read the app record to get its URLs:

    gddy hosting app get --app-id $APP_ID --fields urls

Deploy updates with the CLI

To deploy new code to an existing app, repeat the upload and publish steps. You don't need to create a new app or re-attach it to a hosting plan.

The following procedure uploads new code and publishes it.

  1. Upload the updated zip:

    gddy hosting source upload --app-id $APP_ID --file ./my-app.zip
  2. Poll until the upload reaches a terminal state:

    gddy hosting source status --app-id $APP_ID --import-id $IMPORT_ID
  3. Publish the update:

    gddy hosting deployment publish --app-id $APP_ID
  4. Poll until the deployment reaches a terminal state:

    gddy hosting deployment get --app-id $APP_ID --deployment-id $DEPLOYMENT_ID

Common errors

The following table lists common errors and recommended actions:

StatusCauseAction
401Expired or revoked PAT, or missing scopeGo to Hosting core concepts for the scopes you need
gddy reports an auth or scope errorNot signed in, or the sign-in lacks a scopeRun gddy auth status, then gddy auth login. Add --scope for each missing scope
429Rate limit exceededBack off and retry. Go to Rate limits for handling guidance
Operation stuck in PENDINGUpstream provisioning delayWait up to two minutes before treating it as failed
Import job FAILEDMalformed zip or build failureCheck the application structure and reupload

Agent & Automation Notes

Scopeshosting.application:create, hosting.application:read, hosting.source:write, hosting.source:read, hosting.deployment:execute, hosting.subscription:read, hosting.subscription:write
Rate limit10–120 req/min per client IP depending on operation
On failureCreating an app, uploading source, and publishing are async. Poll the status endpoint for each until it reaches a terminal state. Attaching a hosting plan is synchronous, so there is nothing to poll.

Last updated on

How is this guide?

On this page