Contributor Docs: Building and Publishing AMIs

Note that currently ALL AMIs will be visible to ALL users via a dropdown in PAT. Please be thoughtful about what you publish.

AMI publishing is performed via Jenkins. Access to Jenkins is restricted to OpenStudio Server core contributors.

Release AMIs

To publish an AMI corresponding to an official OpenStudio Server release:

1. Merge release code into master
2. Visit the master branch of OpenStudio-server in Jenkins and click 'You Ready?' and 'Yes'. The new AMI will be appended to the list available on S3. Note that the AMI name is determined by the combination of VERSION and VERSION_EXT in version.rb and republishing for each unique AMI name is not allowed without manual removal of the existing AMI. Please use the VERSION_EXT for pre-release versions according to conventions -alpha#, -beta# or -rc#, where # is an incrementing integer beginning with 0. For example: '-rc0', '-rc1', etc.

Custom AMIs

Custom AMIs are published as one-offs to support ad hoc feature requests, bug fixes, and testing that falls outside of our standard release and testing workflow.

Modification to base AMI (no changes required to Docker image)

1. Create a branch. Branches used for creating AMIs that are older than 30 days will be discarded.
2. Commit modification to files. Note that changes to many of these files would require a custom openstudio-server Docker image.
3. Modify Jenkinsfile to allow AMI publishing from your new branch by replacing "master" with your branch name in stage 'You Ready?' and stage 'Build AMI'.
4. Update version.rb to populate a representative value for VERSION_EXT. By convention we append a zero-indexed version number that can be incremented. For example: -largescale0
5. Modify defaults['dockertag_ext'] to be empty. The AMI will be built with the main Docker image for this OSS version rather than looking for one that was published specifically for this version + version_ext combination.
6. Log in to the Jenkins dashboard. This is restricted to the core development team. Drill down to OpenStudio-server and your branch. Click the 'You Ready' box when it looks partially complete and 'Yes' to publish the AMI.
7. Once the ami is published, it should be appended to the list available on S3

Build using custom Docker image

In many cases, changes to core OpenStudio Server code will require a custom OpenStudio Server Docker image to be published.

1. Follow guide to publish custom Docker image.
2. Modify Jenkinsfile to allow AMI publishing from your new branch by replacing "master" with your branch name in stage 'You Ready?' and stage 'Build AMI'.
3. Ensure that version.rb version and extention correspond to Docker image tagged in step 1.
4. Log in to the Jenkins dashboard. This is restricted to the core development team. Drill down to OpenStudio-server and your branch. Click the 'You Ready' box when it looks partially complete and 'Yes' to publish the AMI.
5. Once the ami is published, it should be appended to the list available on S3

Additional Resources

Further documentation of the AMI build script can be found in the deployment readme.