@atomist/sample-sdm NPM

sample-sdm

Instance of an Atomist Software Delivery Machine that can be used as a sample or run for real on your Java and TypeScript projects.

What is a Software Delivery Machine?

A software delivery machine is a development process in a box.

It automates all steps in the flow from commit to production (potentially via staging environments), and many other actions, using the consistent model provided by the Atomist API for software.

Many teams have a blueprint in their mind for how they'd like to deliver software and ease their day to day work, but find it hard to realize. A Software Delivery Machine makes it possible.

The concept is explained in detail in Rod Johnson's blog Why you need a Software Delivery Machine. This video shows it in action.

Please see the Atomist SDM library for explanation on what an SDM can do. The present document describes how to get yours running.

Get Started

This delivery machine feeds on the Atomist API. You'll need to be a member of an Atomist workspace to run it. Create your own by enrolling at atomist.com.

Things work best if you install an org webhook, so that Atomist receives events for all your GitHub repos.

Get your Software Delivery Machine

If the Atomist bot is in your Slack team, type @atomist create sdm to have Atomist create a personalized version of this repository for you.

You can fork and clone this repository.

Run Locally

This is an Atomist automation client. See run an automation client for instructions on how to set up your environment and run it under Node.js.

See integrations for additional prerequisites according to the projects you're building.

The client logs to the console so you can see it go. Once it runs, here are some things to do:

Start a new project

In Slack, @atomist create spring. This will create a Spring Boot repository. The SDM will build it!

To enable deployment beyond the local one, @atomist enable deploy.

Push to an existing repository

If you have any Java or Node projects in your GitHub org, try linking one to a Slack channel (@atomist link repo), and then push to it. You'll see Atomist react to the push, and the SDM might have some Goals it can complete.

Customize

Every organization has a different environment and different needs. Your software delivery machine is yours: change the code and do what helps you.

In atomist.config.ts, you can choose the machine to start with. cloudFoundryMachine and k8sMachine take care of the whole delivery process from project creation through deployment, while other machines focus only on one aspect, such as project creation, static analysis or autofixing problems in repositories.

Atomist is about developing your development experience by using your coding skills. Change the code, restart, and see your new automations and changed behavior across all your projects, within seconds.

The rest of this README describes some changes you might make.

About this Software Delivery Machine

Implementations of Atomist

Atomist is a flexible system, enabling you to build your own automations or use those provided by Atomist or third parties.

This repository is a reference implementation of Atomist, which focuses on the goals of a typical delivery flow. You can fork it and modify it as the starting point for your own Atomist implementation, or use it purely as a reference.

Concepts

This repository shows how Atomist can automate important tasks and improve your delivery flow. Specifically:

How Atomist command handlers can be used to create services the right way every time, and help keep them up to date
How Atomist event handlers can drive and improve a custom delivery experience, from commit through to deployment and testing

It demonstrates Atomist as the API for software, exposing

What we know: The Atomist cortex, accessible through GraphQL queries and subscription joins
What just happened: An event, triggered by a GraphQL subscription, which is contextualized with the existing knowledge
What you're working on: A library that enables you to comprehend and manipulate the source code you're working on.

Atomist is not tied to GitHub, but this repository focuses on using Atomist with GitHub.com or GitHub Enterprise.

Key Functionality

The following key functionality of this project will be available when you run this automation client in your team:

Project creation for Spring. Atomist is not Spring specific, but we use Spring boot as an illustration here. Try @atomist create spring. The seed project used by default will be spring-team/spring-rest-seed.
- If you want to add or modify the content of generated projects, modify CustomSpringBootGeneratorParameters.ts to specify your own seed. Just about any Spring Boot project will work as the transformation of a seed project is quite forgiving, and parses the seed to find the location and name of the @SpringBootApplication class, rather than relying on hard coding.
- To perform sophisticated changes, such as dynamically computing content, modify the code in springBootGenerator.ts.
Delivery pipeline to either Kubernetes or Pivotal Cloud Foundry for Spring Boot projects. This includes automatic local deployment of non-default branches on the same node as the automation client. The delivery pipeline is automatically triggered on pushes.
Upgrading Spring Boot version across one or many repositories. Try @atomist try to upgrade spring boot. This will create a branch upgrading to Spring Boot 1.5.9 and wait for the build to complete. If the build succeeds, a PR will be created; if it fails, an issue will be created linking to the failed build log and offending branch. To choose a specific Spring Boot version, or see what happens when a bogus version triggers a failure, try @atomist try to upgrade spring boot desiredBootVersion=<version>. If you run such a command in a channel linked to an Atomist repository, it will affect only that repository. If you run it in a channel that is not linked, it will affect all repositories by default. You can add a targets.repos=<regex> parameter to specify a regular expression to target a subset of repo names. For example: @atomist try to upgrade spring boot targets.repos=test.*.

Plugging in Third Party Tools

This repo shows the use of Atomist to perform many steps itself. However, each of the goals used by Atomist here is pluggable.

It's also easy to integrate third party tools like Checkstyle.

Integrating CI tools

One of the tools you are most likely to integrate is CI. For example, you can integrate Jenkins, Travis or Circle CI with Atomist so that these tools are responsible for build. This has potential advantages in terms of scheduling and repeatability of environments.

Integrating a CI tool with Atomist is simple. Simply invoke Atomist hooks to send events around build and artifact creation.

If integrating CI tools, we recommend the following:

CI tools are great for building and generating artifacts. They are often abused as a PaaS for bash. If you find your CI usage has you programming in bash or YML, consider whether invoking such operations from Atomist event handlers might be a better model.
Use Atomist generators to create your CI files, and Atomist editors to keep them in synch, minimizing inconsistency.

Example: Integrating Travis

tbc

Integrating APM tools

Integrating with Static Analysis Tools

Any tool that runs on code, such as Checkstyle, can easily be integrated.

Use shell. node is good for this

Integrations

Choose a machine

You must set environment variables to choose a machine, if you override the default.

export MACHINE_PATH="./software-delivery-machine/machines"
export MACHINE_NAME="cloudFoundrySoftwareDeliveryMachine"

Local HTTP server

To run a local HTTP server to invoke via curl or for smoke testing, please set the following environment variable:

export LOCAL_ATOMIST_ADMIN_PASSWORD="<value>"

Java

To build Java projects on the automation client node, you'll need:

JDK, for Maven and Checkstyle
Maven, with mvn on the path

Node

To build Node projects on the automation client node, you'll need:

npm - v 5.8.0 or above
node

Configuration

The following configuration should be in your ~/.atomist/client.config.json in order to successfully connect your SDM:

{
  "token": "<your github token>",
  "teamIds": [
    "<your team id>"
  ],
  "sdm": {
    "rolar": {
      "url": "https://rolar.cfapps.io"
    },
    "graphviz": {
        "url": "<optional url to graphviz service>"
    },
    "cloudfoundry": {
      "api": "https://api.run.pivotal.io",
      "user": "<your Pivotal Cloud Foundry user name>",
      "password": "<your Pivotal Cloud Foundry password>",
      "org": "<your Pivotal Cloud Foundry organization name>",
      "spaces": {
        "production": "<your Pivotal Cloud Foundry production space name within your org>",
        "staging": "<your Pivotal Cloud Foundry staging space name within your org>"
      }
    },
    "checkstyle": {
      "enabled": false,
      "reviewOnlyChangedFiles": true,
      "path": "/Users/cdupuis/Development/atomist/sample-sdm/test/checkstyle-8.8-all.jar"
    }
  }
}

Checkstyle

Checkstyle is a style-checker for Java. For the optional Checkstyle integration to work, set up two Checkstyle configuration as shown above.

Get checkstyle-8.8-all.jar from Checkstyle's download page.

Cloud Foundry

This SDM allows deployment to Pivotal Cloud Foundry. For deployment to work you need to set your user, password and org of your Cloud Foundry account. Additionally please configure two spaces to be used for staging and production deployments.

Kubernetes

The kubernetesSoftwareDevelopmentMachine included here deploys to an Atomist sandbox kubernetes environment, using k8-automation which we run inside our cluster. You can deploy the Spring Boot projects created with @atomist create spring here, in order to try out the Kubernetes integration with the SDM.