Skip to content

Custom Deployment

The Custom Deployment method enables application code to be developed in a version control system outside of an application’s wpcomvip GitHub repository. The developed code can then be deployed to a VIP Platform environment with VIP-CLI or a continuous deployment method.

Detailed Build, Prepare, and Deployment logs for code deployments made with the Custom Deployment method can be reviewed in the Deployments panel of the environment’s VIP Dashboard.

Limitations

  • Custom Deployment can only be enabled for a WordPress application environment.
  • The code for deployment must include a complete copy of an application’s plugin(s), theme(s), and custom code and be formatted according to the required structure of the VIP WordPress skeleton. Upon decompressing, the code must be located within a root folder.
  • A directory that contains the code for deployment must be archived as either .tar.gz, .tgz, or .zip type.
  • The allowed characters for the name of the archived file are limited to letters (A-Z, a-z), numbers (0-9), hyphens (-), underscores (_), and periods (.).
  • For security concerns, including symbolic links (symlinks) within the archived file is prohibited.
  • The maximum size for the archived file is 4 GB.

Caution

Only application code in a wpcomvip GitHub repository is eligible to receive security or performance-related hotfixes that are occasionally made by the WPVIP team by pull request.

Code that is deployed directly to an environment with the Custom Deployment method:

The archived file for a Custom Deployment should not contain a node_modules directory. It is likely for a node_modules directory to contain platform-specific binary files that cannot be run. Deploying these files can cause performance issues for the application.

Access

Prerequisite

To access, enable, or disable Custom Deployment, a user must have at minimum an Org admin role or an App admin role for that application.

To access the Custom Deployments setting option:

  1. Navigate to the VIP Dashboard for an application.
  2. Select an environment from the dropdown located at the upper left of the dashboard.
  3. Select “Code” from the sidebar navigation at the left of the screen.
  4. Select “Repository Management” from the navigation submenu.

Enable Custom Deployment

Within the “Repository Management” panel of the VIP Dashboard:

  1. Select the radio button for the option labeled “Custom Deployment“.
  2. Select the button labeled “Save Changes“.
  3. Select the button labeled “Enable” in the confirmation modal.

Tokens

Performing a Custom Deployment with VIP-CLI or a continuous integration process requires a token to be generated and assigned to the WPVIP_DEPLOY_TOKEN environment variable. Tokens must be generated within the VIP Dashboard for the target environment. Tokens can only be generated and retrieved at a time when Custom Deployment is enabled for that environment. A Custom Deployment token expires 1 year after it is generated.

Generate a token

Generate a token for Custom Deployment and retrieve its value. A token’s value is only made available in the last step of the generation process, and cannot be retrieved at any other time in any other way.

  1. Navigate to the VIP Dashboard for an application.
  2. Select an environment from the environment dropdown located at the upper left of the VIP Dashboard.
  3. Select “Code” from the sidebar navigation at the left of the screen.
  4. Select “Repository Management” from the navigation submenu.
  5. Select the button labeled “Generate Token“.
  6. Select the button labeled “Copy” to add the value of the token to the clipboard of the user’s local machine.

The value of the token should be stored in a secure location (e.g. a password manager application). A new token can be generated if an existing token’s value is lost or if a token has expired.

List of generated tokens

A list of Custom Deployment tokens that have been generated for an environment can be managed in a table in the lower portion of the “Repository Management” panel.

Information related to each token is displayed across five columns.

  • Token ID: Numerical identifier for the token.
  • Expiry: The date and time of the token’s expiration.
  • Last Used: The date and time of the most recent use of the for a Custom Deployment.
  • Issuer: First and last name values of the user who generated the token.
  • Action: A button labeled “Delete” can be selected to delete the token.

Custom Deployment with VIP-CLI

Prerequisites

Code that was developed in a repository other than an application’s wpcomvip GitHub repository can be deployed with VIP-CLI to a VIP Platform environment that has Custom Deployment enabled.

VIP-CLI command examples

For demonstration purposes, the <app-name> value example-app and the <env> value develop are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.

Validate the archived file

VIP-CLI command: vip app deploy validate

The vip app deploy validate VIP-CLI command scans the contents of an archived file prepared for a Custom Deployment to ensure that the contents are formatted according to the required structure of the VIP WordPress skeleton.

An archived file should not be deployed to a VIP Platform environment until the vip app deploy validate command can successfully run with no reported issues.

In this example command and output, the vip app deploy validate command is run against an archived file named codebase.zip on the user’s local machine and no errors are found:

$ vip app deploy validate codebase.zip
✓ Compressed file has been successfully validated with no errors!

This example command and output demonstrate the informative error message that will be returned if issues are found within the directory structure of the archived file:

$ vip app deploy validate codebase.zip
Error:  Missing `themes` directory from root folder!
Debug:  VIP-CLI v3.4.0, Node v18.17.1, darwin 23.5.0 arm64

Deploy the archived file

VIP-CLI command: vip app deploy

The vip app deploy command requires the WPVIP_DEPLOY_TOKEN environment variable to be passed with the value of a valid Custom Deployment token assigned to it.

When performing a Custom Deployment with VIP-CLI, a description of the deploy can be passed with the --message option. The value can be passed within single (e.g. 'value‘) or double quotes (e.g. "value"). The passed value for the deploy will appear on the “Deployments” panel of the VIP Dashboard in the column labeled “Description“.

In this example command and output the vip app deploy command is used to deploy an archived file named example-file.tar. The command targets the production environment of the “example-app” application, and the token value 1234 is assigned to the environment variable WPVIP_DEPLOY_TOKEN:

$ WPVIP_DEPLOY_TOKEN=1234 vip @example-app.develop app deploy example-file.tar
✔ You are about to deploy to a un-launched PRODUCTION site mytestsite.go-vip.net.
Type 'EXAMPLE-APP.GO-VIP.NET' (without the quotes) to continue:
 · EXAMPLE-APP.GO-VIP.NET

=============================================================
Processing the file for deployment to your environment...
✓ Uploading file 
✓ Triggering deployment 

✅ 20240613214605-example-app.zip has been sent for deployment to example-app.go-vip.net. 
To check deployment status, go to VIP Dashboard: https://dashboard.wpvip.com/apps/8886/production/code/deployments

Last updated: November 29, 2024

Relevant to

  • WordPress