Sitecore JSS Meets TeamCity
Starting to use Sitecore JSS may seem simple at times (after all you can get started with just 4 commands); however, the journey can quickly overwhelm teams steeped in traditional ASP.NET MVC Sitecore development. Teams are introduced to new programming languages, front-end frameworks, development tools, and build and deployment processes.
In this blog, I will walk through a sample build and deployment process for a React JS Sitecore JSS application using TeamCity to deploy to an Azure PaaS Sitecore environment (XM single). Before I jump into the details, here is a little background on the project and some things to consider when creating your own build process.
- One of the first decisions you will need to make is whether to follow a Code-First or Sitecore-First development workflow. This example follows a Code-First approach. You can read more about the different approaches here.
- Choose your deployment topology. This example uses the Integrated Topology. You can read more about the different topologies here.
- Select your build and deployment tool(s). In this case, I am using TeamCity for both the build and deployment process. There are many choices, but many of the same concepts can be applied to your tool of choice.
- Configure parameters for environment settings. This allows environment specific settings to be controlled outside of the code and potentially by another team that controls the environments and infrastructure. It also allows the build process to be copied and only modify a few settings for a new environment or project.
- In this project, the Code-First content is also deployed to a shared Development environment. Deploying content with code is generally not a good practice. This is a temporary process and is only used for testing purposes.
- Apply best practices to secure your tools and any sensitive information. This will not be discussed in this blog; however, it should not be overlooked when creating your own build process.
Build Setup
Without further ado, here is the TeamCity build configuration setup.Project setup
Create a project and any sub-projects to help organize the build configurations. In this example, I have created one project with a subproject for Development.Add your VCS root for the code repository hook. I like to set the Default branch to use a parameter “%BranchName%”, so that can be configured at the subproject or build configuration level.
Add parameters at the project level and leave the values blank. Edit and override these values at the subproject level to set the appropriate Development environment settings.
Build Configuration
Create a build configuration for the application.If you want to Archive the build output for retrieval or investigation purposes, add “out.zip" to the Archive paths setting
To prevent multiple builds running simultaneously, set the build option “Limit the number of simultaneously running builds” to 1
Set the Clean Build option in the Version Control Settings by checking the option for "Delete all files in the checkout directory before the build". This will ensure older versions of the generated JavaScript and CSS files are removed from the build working directory.
Add a build trigger to automate the build process. In this example, I added a “VCS Trigger” to build when code is committed to the appropriate branch in the code repository. I have set the BranchName parameter in the Development subject to “refs/heads/develop” and builds will trigger off of this branch.
Now it is time to start adding steps to the build. The build will contain 6 steps.
- NPM Install
- Create Sitecore JSS Config
- JSS Build
- Archive Output
- JSS Deploy Items (wipe)
- Push to Azure
Step 1: NPM install
This step will download and install the dependent packages for the project.
Step 2: Create Sitecore JSS Config
This step will update the configuration used by the Sitecore JSS application. Use the Powershell runner and enter the following script.Set-Content -Path "scjssconfig.json" -Value @" { "sitecore": { "instancePath": "%InstancePath%", "apiKey": "%ApiKey%", "deploySecret": "%DeploySecret%", "deployUrl": "%DeployUrl%", "layoutServiceHost": "%LayoutServiceHost%" } } "@
Step 3: JSS Build
This step will build the application bundle. Use the Command line runner and enter the following in the Custom script field.jss build
Step 4: Archive Output
This step will create a zip archive with the folder structure needed when deploying to the Sitecore web server. Use the Powershell runner and enter the following script.#Create the output directory md -path out/dist/%JssAppName% #Move build output Copy-Item -Path build\* -Recurse -Destination out/dist/%JssAppName% -Force -Verbose #Create zip Compress-Archive -Path out\dist -DestinationPath out.zip -Force
Step 5: JSS Deploy Items (wipe)
This step will deploy the Sitecore templates, renderings, dictionary items as well as the Code-First content. As discussed before, the deployment of content is generally not recommended. The content deployment can be removed by eliminating the “-c” parameter. Use the Command line runner and enter the following in the Custom script field.jss deploy items -c -d -w --unattendedWipe
Step 6: Push to Azure
This step will push the code to the Azure PaaS Web Application for the XM Single Sitecore instance. The AzureWebUsername and AzureWebPassword are generated in Azure under the Deployment Center for the Web App instance. Select the Ftp option and add a new account to use for the deployment and enter them in the Development subproject parameters. The build step will also remove the JSS app folder prior to deployment to provide a clean target.For this build step, use the Powershell runner and enter the following script.
$username = "%AzureWebUsername%" $password = "%AzureWebPassword%" $filePath = "out.zip" $jssAppName = "%JssAppName%" $apiBaseUrl = "https://%AzureWebAppName%.scm.azurewebsites.net/api" $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password))) $CommandBody = @{ command = 'rmdir ' + $jssAppName + ' /s /q' dir = 'site\\wwwroot\dist' } $CommandJson = $CommandBody | ConvertTo-Json #remove JSS app contents Invoke-RestMethod -Uri $apiBaseUrl/command -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Method POST -Body $CommandJson -ContentType 'application/json' #deploy new JSS app from zip Invoke-RestMethod -Uri $apiBaseUrl/zipdeploy -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Method POST -InFile $filePath -ContentType "multipart/form-data"
Comments
Post a Comment