Platform Deployment

Harmony Platform build results in build artifacts that are simple to scale and deploy. They allow for optimization and scale of applications based on business needs while keeping code organization independent from your production infrastructure.

Using Bit and Harmony, you can produce a single binary build artifact for each of your application runtimes, the produced output of a standard platform build includes:

• Binary artifact for the backend.
• Code-split and optimized UI application bundle.

This allows for optimized security, safety and performance for your software.

Orchestration of a platform deployment on a Kubernetes cluster

To configure the default Kubernetes deployer, first install it:

bit install @bitdev/symphony.deployers.kubernetes

Copied

Then use the aspect in your application shell:

import { KubernetesAspect } from '@bitdev/symphony.deployers.kubernetes';
import { SymphonyPlatformAspect } from '@bitdev/symphony.symphony-platform';

export const MyPlatform = HarmonyPlatform.from({
  name: 'my-platform',
  platform: [SymphonyPlatformAspect, {
    name: 'My platform',
    domain: 'example.com',
  }],
  
  aspects: [[
    KubernetesAspect, {
      auth: {
        // configure your kubernetes cluster.
        basic: {
          server: 'http://1.2.3.4',
          token: process.env.KUBE_USER_TOKEN // set environment variables as Ripple CI secrets.
        }
      },
      // configure your docker registry.
      docker: {
        imagePrefix: 'dockerhub-account',
        auth: {
          username: 'ci-user',
          password: process.env.DOCKER_TOKEN // set DOCKER_TOKEN environment variables as Ripple CI secrets.
        }
      }
  }]],
});

Copied

Once configured, the shell application deployment pipelines will be invoked during the release pipeline, when you run the tag or snap commands:

bit tag --message 'releasing my feature' --major

Copied

Make sure to configure the environment variable secrets in Ripple CI secrets, making them available for deployment.

Initiate the release CI job:

bit export

Copied

The CI pipeline automatically releases your application to the specified Kubernetes cluster. You can adjust the deployment of each runtime to use the below list of supported deployers or build your own.

Use specific cloud providers to ease the deployment to the cloud provider of your choice.

Google Cloud

AWS

Azure

Configuring a deployment to Google Cloud:

import { KubernetesAspect } from '@bitdev/symphony.deployers.kubernetes';
import { GcpAspect } from '@bitdev/symphony.deployers.gcp';
import { SymphonyPlatformAspect } from '@bitdev/symphony.symphony-platform';

export const MyPlatform = HarmonyPlatform.from({
  name: 'my-platform',
  platform: [SymphonyPlatformAspect, {
    name: 'My platform',
    domain: 'example.com',
  }],
  
  aspects: [
    KubernetesAspect,
    [GcpAspect, {
      clusterName: 'acme-platform',
      zone: 'us-central1',
      keyJson: process.env.GCP_ACCESS_KEY
    }]
  ],
});

Copied

It is recommended to automate the deployment to pre-production from the main lane, and deploy to production separately after carefully testing changes on the pre-production environment.

Each version of the platform component includes its deployment artifact. Use the artifacts command to fetch it:

bit artifacts pied.pied-piper/pied-piper --out-dir deploy

Copied

Now you can run the deployment:

node path/to/artifact/my-platform.cjs deploy

Copied

When running the deployment, make sure to authenticate with your Docker registry and Kubernetes cluster, or cloud provider.

To rollback to any past version, use the artifacts command to fetch any of your past artifacts:

bit artifacts pied.pied-piper/pied-piper@1.0.0 --out-dir deploy

Copied

Run the deployment:

node path/to/artifact/my-platform.cjs deploy

Copied

You can customize and control every level of the platform deployment.

When deploying on Kubernetes, you can register additional setup instructions. They will be executed during the deployment process:

export class AcmePlatformNode {
  static dependencies = [KubernetesAspect];
  
  static async provider([kubernetes]: [KubernetesNode]) {
    const acmePlatform = new AcmePlatform();

    kubernetes.registerSetup([
      {
        name: 'mongo-db',
        yamls: []
      }
    ])

    return acmePlatform;
  }
}

Copied

Symphony has a default implementation of an API gateway, supporting Express and GraphQL. You can replace the API gateway implementation with your own if needed.

By default, the browser runtime leverages Vite (with SSR support) for bundling your application. You can replace the bundler with other tools, as needed.

You can override and use configuration files for specific services using the backend server DeployOptions.

Alternatively, you can implement your own deploy function using the deploy property key in your Harmony platform:

// my-platform.bit-app.ts
import { HarmonyDeployContext } from '@bitdev/harmony.harmony-platform';

export async function platformBuildFunction(context: HarmonyDeployContext) {
  // echos the platform path and a list of build artifacts created for each of the platform runtimes.
  console.log(context.capsule.path, context.runtimeArtifacts); 

  return {
    // used for display on bit cloud for staging and production environments.
    url: 'my-platform.com'
  }
}

Copied

Find more information on the API available in the Harmony Deploy Context API reference. To learn more about the application context, head to the Deploying apps section.

You can test your deployment locally without creating a new version to your platform (be careful, as this will trigger your deploy pipeline):

bit build --include-tag

Copied

To deploy a microservice, a common practice is to invoke the NodeJS runtime with a deploy argument and handle deployment from within the platform aspect.

Harmony gives you granular control when running your platform, app or services.

Run the application:

node path/to/artifact/my-platform.cjs

Copied

Run a specific backend service:

node path/to/artifact/my-platform.cjs people

Copied

Run a specific frontend application:

node path/to/artifact/my-platform.cjs people

Copied