Zum Hauptinhalt springen

Deploying to production

Deploying with Nova TeamCity module​

You can use the Guidewire Nova TeamCity module to generate TeamCity pipelines for your Jutro app deployment. You need to run this from your app's home directory to create the necessary config files and a deployment in TeamCity.

Pre-requisites​

  • SSH Key setup for your service account

    • This allows TeamCity to interact with your git repo

  • Parent project in TeamCity - If you do not have a TeamCity project for your pod, create a ticket in the Engineering Services Portal

  • On-boarding onto Atmos Microservice Platform

    • Atmos prompts for your AWS access key id/secret when running nova teamcity

  • Set up your connection to the required repositories in Artifactory

    • Get your Identity Token from Artifactory
      1. From your Okta homepage, log in to Artifactory
      2. Click your avatar in the top right-hand corner and select Edit Profile
      3. In the Authentication settings section, click Generate an Identity Token
      4. Set meaningful description and click Next.
      5. Copy the Identity Token, as it will only be displayed once.
    • Run the following command: 
      npm config set registry https://artifactory.guidewire.com/artifactory/api/npm/jutro-suite-npm-dev/
      npm login --registry https://artifactory.guidewire.com/artifactory/api/npm/jutro-suite-npm-dev/
    • Follow the prompts in the terminal.
      1. Enter your username without @guidewire.com
      2. Instead of typing your password, paste your Identity Token

    This saves the config in your .npmrc file.

Note: When the atmosdeploy-jutro:18.14.2 image is used for your app's CI pipelines, the minimum requirement is to have docker.server.version agent's spec with 20.10.13.

Quick start​

  1. Create a Jutro app
  2. Generate TeamCity projects, connections, parameters, and Kotlin DSL using following command: 
    npm init yo @jutro/generator-jhipster-teamcity-jutro
  3. Push the generated code to git (you need to do that in the main branch)
  4. Update TeamCity to use the generated pipeline using the following command: 
    npm init yo @jutro/generator-jhipster-teamcity-jutro:apply
Warning: The TeamCity generator was previously called @devex/generator-jhipster-nova-teamcity-jutro. The configuration stored in yo-rc.json is referenced by the generator name, so if the project was initially created with the old generator, it will fail with new one. Make sure you update your yo-rc.json:
{
-  "@devex/generator-jhipster-nova-teamcity-jutro": {
+  "@jutro/generator-jhipster-teamcity-jutro": {
    "teamcityUrl": "https://gwre-devexp-ci-production-devci.gwre-devops.net",

Upgrading your pipeline​

Note that you can run nova upgrade only for Nova generated Spring Boot applications.

To upgrade your TeamCity pipeline for Jutro app, you should run npm init yo @jutro/generator-jhipster-teamcity-jutro. If you have customized your TeamCity pipeline, you will have to reapply your customizations manually afterwards.

Additional info​

Configure cache control​

The recommended cache control configuration for Jutro apps is based on two principles:

  • Static assets, such as images must be cached for a year. In the base configuration, every asset that is not dynamic content is considered a static asset, or a file that uses a cache busting technique.
  • Dynamic content, such as HTML, JSON, and JavaScript files cannot be cached. The exceptions are files that are using a cache busting technique, such as appending a hash to the file name.

To configure cache control in your configuration file, set the following directives in cache-control:

  • For static assets:
    • max-age:31536000
    • public
    • must-revalidate
    • proxy-revalidate
  • For dynamic content:
    • max-age:0
    • no-store
    • public
    • must-revalidate
    • proxy-revalidate

If you've generated your Jutro app configuration using the TeamCity generator, the base cache control is already configured in the settings.kts file, as shown in the following example. If your app has additional dynamic content files, you can add them to the --exclude and --include parameters in the respective commands.

  aws s3 sync ${BUILD_FOLDER_NAME} ${TARGET_LOCATION}/ ${S3_PARAMS} --delete \
   --cache-control 'max-age=31536000, public, must-revalidate, proxy-revalidate' \
   --exclude '*.html' \
   --exclude '*.json' \
   --exclude 'OidcServiceWorker.js' \
   --exclude 'OidcTrustedDomains.js' \
   --exclude 'jutro-micro-frontends.js'

  aws s3 sync ${BUILD_FOLDER_NAME} ${TARGET_LOCATION}/ ${S3_PARAMS} \
   --cache-control 'max-age=0, no-store, public, must-revalidate, proxy-revalidate' \
   --expires '0' \
   --exclude '*' \
   --include '*.html' \
   --include '*.json' \
   --include 'OidcServiceWorker.js' \
   --include 'OidcTrustedDomains.js' \
   --include 'jutro-micro-frontends.js'

Atmos with Nova​

Prerequisite: Access AWS

Using kubectl & Accessing K8s Dashboard: Connecting to Kubernetes

Note: When logged in to the K8s Dashboard, you will only have access to your pod's namespace, so make sure you select your pod's namespace on the left.

On any other namespace, you will see unauthorized errors.

Pipeline​

The Jutro pipeline comprises of the following build configurations;

  • Test - This has steps to run your npm tests.
  • Build and Deploy to Dev - This will build your Jutro app and push it to AWS S3, which is exposed through the atmos-dev cluster. You can also deploy a non-main branch to a custom namespace by selecting the branch from the dropdown menu at the top of the TeamCity page.
  • Build and Deploy to Int - This will build your Jutro app and push it to AWS S3, which is exposed through the atmos-int cluster.
  • Build and Deploy to Staging - This will build your Jutro app and push it to AWS S3, which is exposed through the atmos-staging cluster.
  • Build and Deploy to Prod - This will build your Jutro app and push it to AWS S3, which is exposed through the atmos-us-east-2 cluster.
  • Release New Version - This will bump your patch/minor/major version and push this tag to the Git repo.

Prompts​

  • Teamcity username: what is your teamcity username? Your Teamcity username for creating microservice project in Teamcity.
  • Teamcity password: what is your teamcity password? Teamcity password. This will be masked and not saved anywhere.
  • Teamcity URL: what is your teamcity server URL? Teamcity url, typically you should accept the default.
  • Teamcity Parent Project Id: what is your teamcity parent project id? Nova will generate Teamcity project under this project. Nova will create hidden parameters for your team's Artifactory credentials, AWS access key id/secret, and application's OAuth2 client secret under this project.
  • Pod Name: What is your Pod name? Name of your pod (all lowercase).
  • Application Git Base URL: what is the SSH base git url of your application? Your git repository url. Specify the SSH URL here.
  • Application Git Default Branch: what is the default branch of your application's git repository (e.g. main)? The default branch is main.
  • Uploaded key name: what is the uploaded key name for pulling from git? (If you don't have a key yet, enter https:). This is the key you have uploaded for pulling from git.
  • S3 Bucket for Static Files: Please enter a name for the S3 bucket you want to create (Prefixed automatically with tenant--) The name of the bucket for your Jutro app's static files.
  • Kubernetes Namespace: What is your Kubernetes namespace? The default one will be pod name. You can customize it to deploy your application to a different namespace.
  • AWS Access Key Id: what is your AWS Access Key Id? Your team's AWS access key for microservice platform. This will be persisted as hidden parameter under your parent project.
  • AWS Access Key Secret: what is your AWS Access Key Secret? Your team's AWS access key secret for microservice platform. This will be persisted as hidden parameter under your parent project.
  • AWS Region: what is your AWS Region? Typically you should accept the default.
  • System Username: what is the Artifactory and Stash username of your pod's service account? Your pod's service account, which can be used for pushing docker images to artifactory. You must not use a personal account here.
  • Artifactory Password: what is the Artifactory Identity Token of your pod's service account? Your service account Artifactory Identity Token. This will be masked and not saved anywhere.
  • Stash Password: what is the Stash password of your pod's service account?
  • Artifactory URL: what is your Artifactory url? Typically you should accept the default.
  • Pod Email: what is the email of your pod? This is your pod's service account email (typically pod-<your pod name>@guidewire.com). This will be used for publishing tags to Git repository and npm login.
  • Kubernetes Department: the code of the department owning the application, for which costs should be allocated. Do not default to CCS! (List of dept codes)[https://guidewireconfluence.atlassian.net/wiki/spaces/CCS/pages/92046341/Department+List+for+Resource+Tagging].
  • Tenant Name: tenant name without the word tenant, for example pod-salinas, usaa, etc., more information under "gwcp:v1:tenant:name" on this Confluence page.

Building a static site​

You can build your app to a static format using:

npm run build

This creates a self-sufficient set of files that you can host on a static web server.

The project is built assuming it is hosted at the server root. To override this, specify the homepage in your package.json. Add it as a root-level property, for example:

{
    // ...
    "scripts": {
    // ...
},
    "homepage": "https://example.com/my-app"
}

Build information​

As part of the build, Jutro app generates build information that can be accessed along with the deployed application.

The information is made available in the form of a JSON file which will be written, by default, to src/assets.

What build information is provided?​

{
  "APPLICATION_NAME": "@jutro/jutro-app", // read from package.json "name" field
  "APPLICATION_VERSION": "1.0.4-next.0", // read from package.json "version" field
  "JUTRO_VERSION": "1.0.4-next.0", // installed Jutro version
  "COMMIT_HASH": "c42d6ed1c" // most recent Git commit hash, if Git is available
}

Disabling the build output​

To disable this feature, simply modify your package.json file to remove the running of the script.

{
  "scripts": {
    "build-old": "npm run write-build-info && cross-env NODE_OPTIONS=--max-old-space-size=4096 GENERATE_SOURCEMAP=false react-app-rewired build && npm run i18n",
    "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 GENERATE_SOURCEMAP=false react-app-rewired build && npm run i18n"
  }
}

Obfuscation​

When deploying your application, remember to obfuscate your code.

In the base configuration of the Jutro app , the build script contains the following parameter: GENERATE_SOURCEMAP=false.

Ensure that you include this in your applications build, and don't remove it from the provided Jutro app template. This is to make sure we do not expose source code outside of Guidewire.

LibNPX​

When running npm init yo @jutro/generator-jhipster-teamcity-jutro, you may experience the following error:

Error: Cannot find module 'libnpx'

If you see this error, from the home directory, run the following command:

npm i libnpx