Skip to main content

How to run custom deployment commands

The Uniform service generates static files and deploys those files to a destination using a component called a "publish provider". Uniform includes publish providers to support a number of CDN and storage services.

The Custom publish provider can be used to deploy files to a location that does not have a dedicated publish provider. This is the solution to use when you need to deploy files to a CDN or storage service that Uniform does not support out-of-the-box. This is also the solution to use when you need to deploy files to your own web server or to a file system folder.

Example#

In this example you will configure the Uniform service to deploy files to a local folder, and then start a web server that uses the local folder as its root directory.

Configure command#

Add the following to your .env file:

UNIFORM_PUBLISH_TARGET=customUNIFORM_PUBLISH_CUSTOM_BEHAVIOR=replace-on-deployUNIFORM_PUBLISH_CUSTOM_COMMAND=npx ncp __DIR__ out && echo "Deployed successfully"
tip

More information on these environment variables is available in the configuration section below.

Let's look at the command more closely. It consists of three separate parts:

  1. npx ncp __DIR__ out - This expression uses the ncp command to copy the files from the DIR directory to the out directory. We need to prefix the command with npx because ncp is an NPM package which isn't globally available on your system's PATH.
    note

    ncp is a file copying command that works in both Windows and Linux, so the same command can work regardless of which operating system the Uniform service is running under.

  2. && - This is an and operator. It ensures the command stops running if the first expression fails.
  3. echo "Deployed successfully" - This indicates to the Uniform service that the custom command completed successfully.

Start local web server#

  1. Open a terminal window (or Command Prompt or PowerShell) in the root folder for the Uniform service.
  2. If the folder out does not already exist, create it.
  3. Enter the following command to start a web server with the folder out as its root:
    npx serve out
tip

This command uses the serve package for the web server. If you have a different tool you prefer, feel free to use that.

Publish from Sitecore#

Publish a Sitecore site that is configured to use your Uniform service. The log from the Uniform service will show details of the deployment process, including the triggering of the custom publish command.

07/02-12:26:31  info: Received deploy request.07/02-12:26:31  info: Deploy request contains ENV variables: config will be merged for the current deploy request07/02-12:26:31  info: ENV delta: {"UNIFORM_PUBLISH_TARGET":"custom" } 07/02-12:26:31  info: Initializing CustomPublishProvider07/02-12:26:31  info: Initializing CustomPublishProvider with command: npx ncp __DIR__ out && echo "Deployed successfully"07/02-12:26:31  info: Creating output dir: C:\...\jss-site-next\.temp\h07/02-12:26:31  info: Starting export for 5 page(s)://architecture/development/marketing/security07/02-12:26:31  info: Starting build and export...07/02-12:26:31  info: UNIFORM_PUBLISH_NEXT_EXPORT_COMMAND is not defined, so switching to default: npx next build && npx next export --outdir "__DIR__" 07/02-12:26:31  info: Starting custom exec nextjs export process (with UNIFORM_API_SITENAME = JssSite)07/02-12:26:31  info: Received deploy status request, ticket: h, message: Generating HTML site files07/02-12:26:47  info: Exporting has succeeded.07/02-12:26:47  info: Creating .timestamp.txt file07/02-12:26:47  info: Starting deployment07/02-12:26:47  info: Deploying C:\...\jss-site-next\.temp\h (CustomPublishProvider)07/02-12:26:47  info: Successfully deployed C:\...\jss-site-next\.temp\h folder07/02-12:26:47  info: Deleting temp dir: C:\...\jss-site-next\.temp\h07/02-12:26:47  info: Temp dir was deleted: C:\...\jss-site-next\.temp\h07/02-12:26:47  info: Received deploy status request, ticket: h, message: Deployment is complete

A lot of useful information is included in the log.

The following lines show that the CustomPublishProvider is being used. It also shows the command that will be run during the deploy process.

07/02-12:26:31  info: Initializing CustomPublishProvider07/02-12:26:31  info: Initializing CustomPublishProvider with command: npx ncp __DIR__ out && echo "Deployed successfully"

The following line shows the point at which the command is actually run. It also shows that the variable __DIR__ was replaced with C:\...\jss-site-next\.temp\h.

07/02-12:26:47  info: Deploying C:\...\jss-site-next\.temp\h (CustomPublishProvider)

Copy files using SSH#

If you are serving the static website from a remote file system, such as a Linux virtual machine, the process is very similar to copying the files locally. The main difference is that instead of using the ncp command to copy files locally, the scp command is used to copy the files using SSH.

note

You need to have an SSH connection configured between the machine running the Uniform service and the remote machine that is hosting the website.

The following is an example that copies files to the default nginx static files directory:

UNIFORM_PUBLISH_CUSTOM_COMMAND=scp -r __DIR__/* user@host:/usr/share/nginx/html

Configuration#

Environment variables are used to tell Uniform which publish provider to use, and to specify settings that the publish provider should use. The following environment variables are required when using the Custom publish provider:

UNIFORM_PUBLISH_TARGET#

Uniform uses this variable to determine which publish provider to use. When using the Custom publish target this variable is always set to custom.

UNIFORM_PUBLISH_CUSTOM_BEHAVIOR#

The following values are supported:

  • replace-on-deploy - All public files, static files and exported files are deployed.
  • update-on-deploy - Deployment is broken into three separate calls: one for public files, one for static files and another for exported files.

UNIFORM_PUBLISH_CUSTOM_COMMAND#

This variable defines the command that is run when the exported files are ready to be deployed. The variable __DIR__ is used in the command to reference the absolute path to the files that were generated.

A custom command must fulfill the following requirements:

  1. The __DIR__ variable must be used in the command.
  2. The command must end with the statement echo 'Deployed successfully'.

The sample commands section below provides examples of how to implement commands using different common technologies.

Sample commands#

The following examples involve the Uniform service triggering scripts. You must make sure that the account used to run the Uniform service has sufficient permissions to be able to execute the script and to access any resources the script interacts with.

Shell script#

If the Uniform service is running on Linux, you can write a publish command using a shell script. The following example will copy the build results to the out folder and then publish the files to Cloudflare.

  1. In the root folder for the Uniform service, create a file post-export.sh:

    rsync -av --no-perms $1 ./outwrangler publish

  2. Add the following publish command to the environment variable:

    UNIFORM_PUBLISH_CUSTOM_COMMAND=". ./post-export.sh '__DIR__' && echo 'Deployed successfully'"

PowerShell script#

You can write a publish command using PowerShell. The following example will copy the build results to the out folder and then publish the files to Cloudflare.

  1. In the root folder for the Uniform service, create a file PostExport.ps1:

    param(    [Parameter(Mandatory = $true)]    $Target)
$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';
robocopy $Target "out" /e /MT:64 /NP
Write-Output "RUNNING WRANGLER PUBLISH..."wrangler publishWrite-Output "WRANGLER COMPLETE"

  2. Add the following publish command to the environment variable:

    UNIFORM_PUBLISH_CUSTOM_COMMAND=powershell.exe ". .\PostExport.ps1 -Target '__DIR__' && echo 'Deployed successfully'"

JavaScript script#

You can write a publish command using JavaScript. The following example will deploy the build results to Vercel using the Vercel Node.js client.

  1. In the root folder for the Uniform service, create a file post-export.js:

    const { createDeployment } = require('@vercel/client');
// Get the __DIR__ path from the argumentsconst [,, deployPath] = process.argv
async function deploy() {let deployment;
for await (const event of createDeployment({    token: process.env.VERCEL_TOKEN,    path: deployPath,})) {    if (event.type === 'ready') {    deployment = event.payload;    break;    }}
return deployment;}

  2. Add the following publish command to the environment variable:

    UNIFORM_PUBLISH_CUSTOM_COMMAND="node ./post-export.js '__DIR__' && echo 'Deployed successfully'"