How to deploy your Node.js app
View as MarkdownDeploy 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.
-
Create the app:
gddy hosting app create --app-type NODEJS --name my-first-app -
Poll until the operation reaches
COMPLETEDorFAILED: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.
-
Zip the app, leaving out
node_modules,.envfiles, and.git:zip -r my-app.zip . -x "node_modules/*" -x ".env*" -x ".git/*" -
Upload the zip:
gddy hosting source upload --app-id $APP_ID --file ./my-app.zip -
Poll until the upload reaches a terminal state:
gddy hosting source status --app-id $APP_ID --import-id $IMPORT_ID -
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.
-
List your web hosting plans:
gddy hosting subscription list --hosting-product WEB_HOSTING -
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.
-
Publish the app:
gddy hosting deployment publish --app-id $APP_ID -
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.
-
Read the app status:
gddy hosting app status --app-id $APP_ID -
Check that
statusisACTIVE, and that thePUBLISHentry invariantshas astatusofACTIVEand alifecycleStateofrunning. The CLI nests these fields underdata. -
Open the
urls.publishaddress 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.
-
Upload the updated zip:
gddy hosting source upload --app-id $APP_ID --file ./my-app.zip -
Poll until the upload reaches a terminal state:
gddy hosting source status --app-id $APP_ID --import-id $IMPORT_ID -
Publish the update:
gddy hosting deployment publish --app-id $APP_ID -
Poll until the deployment reaches a terminal state:
gddy hosting deployment get --app-id $APP_ID --deployment-id $DEPLOYMENT_ID
Prerequisites for the API
The following prerequisites are required before you can deploy your Node.js app:
- a Personal Access Token with the following scopes:
hosting.application:create,hosting.application:read,hosting.source:write,hosting.source:read,hosting.deployment:execute,hosting.subscription:read,hosting.subscription:write - 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 API
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 API
POST /apps?appType=NODEJS accepts a name and returns 202 Accepted with an AppOperation, including a links[rel=self] URL. Poll that URL with GET /app-operations/{operationId} until the status reaches COMPLETED (success) or FAILED. The curl examples use $OPERATION_ID for the operationId in the create response and $APP_ID for app.id in the completed operation.
-
Create the app:
curl -s -X POST "$BASE_URL/v1/hosting/apps?appType=NODEJS" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "my-first-app" }' -
Poll until the operation reaches
COMPLETEDorFAILED:curl -s "$BASE_URL/v1/hosting/app-operations/$OPERATION_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq '{status: .status, appId: .app.id}'
Upload source and preview your app with the API
POST /apps/{appId}/imports accepts a zip as multipart/form-data and returns 202 Accepted with a SourceImport operation. Poll it with GET /apps/{appId}/imports/{importId} until the status reaches COMPLETED or FAILED. The curl examples use $IMPORT_ID for the importId in the response. After the import reaches COMPLETED, your code runs on the preview variant, which works without a hosting plan. The preview URL is private, so sign in to your GoDaddy account to open it. Go to Get app URLs with the API for the request that returns it.
The following procedure zips your app, uploads it, and polls the import.
-
Zip the app, leaving out
node_modules,.envfiles, and.git:zip -r my-app.zip . -x "node_modules/*" -x ".env*" -x ".git/*" -
Upload the zip:
curl -s -X POST "$BASE_URL/v1/hosting/apps/$APP_ID/imports" \ -H "Authorization: Bearer $GODADDY_PAT" \ -F "file=@./my-app.zip" -
Poll until the upload reaches a terminal state:
curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/imports/$IMPORT_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .status
Attach to hosting plan with the API
Before you can publish a Node.js app, you must attach it to a web hosting subscription. Use a valid subscription ID from your GoDaddy account (GET /subscriptions?hostingProduct=WEB_HOSTING lists the plans on it). PUT /apps/{appId}/subscription attaches the app to one, and the call is synchronous, so there's no operation to poll. The curl example uses $SUBSCRIPTION_ID for the subscriptionId of a plan with an available slot. Go to Attach to a hosting plan for detailed guidance.
-
Attach the app to a subscription:
curl -s -X PUT "$BASE_URL/v1/hosting/apps/$APP_ID/subscription" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{ "subscriptionId": "'$SUBSCRIPTION_ID'" }'
Publish your app with the API
POST /apps/{appId}/deployments builds the latest source, deploys it to the publish environment, and returns 202 Accepted with a Deployment. Poll it with GET /apps/{appId}/deployments/{deploymentId} until the status reaches COMPLETED or FAILED. The curl examples use $DEPLOYMENT_ID for the deploymentId in the response.
-
Publish the app:
curl -s -X POST "$BASE_URL/v1/hosting/apps/$APP_ID/deployments" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Content-Type: application/json" \ -d '{}' -
Poll until deployment reaches a terminal state:
curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/deployments/$DEPLOYMENT_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .status
Verify with the API
GET /apps/{appId}/status returns the application lifecycle in top-level 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.
-
Read the app status:
curl -s "$BASE_URL/v1/hosting/apps/$APP_ID/status" \ -H "Authorization: Bearer $GODADDY_PAT" | jq . -
Check that
statusisACTIVE, and that thePUBLISHentry invariantshas astatusofACTIVEand alifecycleStateofrunning. -
Open the
urls.publishaddress to see the live app. The next step shows how to read it.
Get app URLs with the API
GET /apps/{appId} returns the full app record, including a urls object with the URL for each environment. Your code is not live at urls.publish until you publish.
-
Read the app record to get its URLs:
curl -s "$BASE_URL/v1/hosting/apps/$APP_ID" \ -H "Authorization: Bearer $GODADDY_PAT" | jq .urls
Deploy updates with the API
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.
-
Upload the updated zip with
POST /apps/{appId}/imports. -
Poll the upload with
GET /apps/{appId}/imports/{importId}until it reaches a terminal state. -
Publish the update with
POST /apps/{appId}/deployments. -
Poll the deployment with
GET /apps/{appId}/deployments/{deploymentId}until it reaches a terminal state.
Common errors
The following table lists common errors and recommended actions:
| Status | Cause | Action |
|---|---|---|
401 | Expired or revoked PAT, or missing scope | Go to Hosting core concepts for the scopes you need |
gddy reports an auth or scope error | Not signed in, or the sign-in lacks a scope | Run gddy auth status, then gddy auth login. Add --scope for each missing scope |
429 | Rate limit exceeded | Back off and retry. Go to Rate limits for handling guidance |
Operation stuck in PENDING | Upstream provisioning delay | Wait up to two minutes before treating it as failed |
Import job FAILED | Malformed zip or build failure | Check the application structure and reupload |
Agent & Automation Notes
hosting.application:create, hosting.application:read, hosting.source:write, hosting.source:read, hosting.deployment:execute, hosting.subscription:read, hosting.subscription:writeRelated
Last updated on
How is this guide?