Skip to main content

Launching an EC2 instance for the Bitrise AMI

We offer a dedicated Bitrise Amazon Machine Image (AMI) to run the Bitrise agent on your own Amazon EC2 instance.

This document guides you through launching an instance on the AWS EC2 console UI. You will also need to connect the instance to your Bitrise Workspace: we strongly recommend using the AWS Secrets Manager to do so.

You can also launch instances via the AWS CLI.Launching an EC2 instance via the AWS CLI

Mac instance

Linux instance

  1. Configure a runner pool and copy the token required for authentication.

  2. Navigate to the EC2 Dashboard.

  3. Allocate a dedicated host on AWS. You will need the automatically generated host ID.

  4. Go to the AWS Marketplace page, and on the left, select Manage subscriptions.

  5. Choose the AMI you need, and select Launch new instance.

    aws-markplace-amis.png

  6. Make sure the software version and the region are correct, then click Continue to launch through EC2.

  7. Fill out the required fields on the Launch an instance page:

    Name and tags section:

    • Name: The name of your instance.

    Instance type section:

    • Instance type: The supported types are: mac2.metal, mac2-m2.metal, mac2-m2pro.metal.

      Dedicated host type

      The selected instance type must match the type of the dedicated host!

    Key pair (login) section:

    • Key pair name - required:

    Network settings section - click Edit to modify the settings:

    • VPC - required: Select a virtual private cloud from the dropdown menu.

    • Subnet: Select your preferred subnet from the dropdown menu, or leave it on No preference.

    • Firewall (security groups): Create a new security group or select an existing one.

    Configure storage section:

    • Set the size of the storage volume in gigabytes:

      For the bare metal macOS AMI, the minimum number is 400 GB but we recommend at least 450.

      For the virtualized macOS AMI, it's 2TB.

      Increasing the disk size

      If you need to increase the disk size from the default 400 GB, re-partition the disk so macOS can use all the allocated storage. You can do this when setting up the instance by adding a script to User data in the Advanced details section: Increasing disk size on a Mac instance.

    • Select a root volume type from the dropdown menu.

      Storage type

      We recommend using at least the gp3 root volume, the higher the IOPS the better.

    Advanced details section:

    • Tenancy: Select the Dedicated host - launch this instance on a dedicated Host option from the dropdown menu.

    • Target host: Select the Host ID option from the dropdown menu.

    • Tenancy host ID: Select the host ID of the previously created dedicated host.

  8. We strongly recommend setting up the connection to your Bitrise workspace during instance creation, using the AWS Secret Manager. This requires adding User data scripts in the Advanced details section: Using the AWS Secret Manager.

    Troubleshooting connection issues

    If you encounter problems with the connection after launching the instance, try connecting to the instance via SSH and troubleshooting the commands one by one: Troubleshooting the instance connection.

    You can learn more about user data in the AWS documentation: User data and the console.

  9. You can also set shell scripts or other custom data in the User data section.

    In the Advanced options for EC2 instances section, you can find recommendations for optimizing your instance with user data:

  10. Click Launch instance.

    The launch can take up to 10-15 minutes. You will see system status checks and instance status checks: once the instance is ready, both checks will be green.

    aws-status-check.png

  1. Navigate to the EC2 Dashboard.

  2. Go to the AWS Marketplace page, and on the left, select Manage subscriptions.

  3. Choose the AMI you need, and select Launch new instance.

    aws-markplace-amis.png

  4. Make sure the software version and the region are correct, then click Continue to launch through EC2.

    Service quotas

    Make sure you have enough service quotas in your selected region to be able to launch as many instances as you need.

  5. Fill out the required fields on the Launch an instance page:

    Name and tags section:

    • Name: The name of your instance.

    Instance type section:

    • Instance type: Select an x86_64 Linux metal instance.

    Key pair (login) section:

    • Key pair name - required:

    Network settings section - click Edit to modify the settings:

    • VPC - required: Select a virtual private cloud from the dropdown menu.

    • Subnet: Select your preferred subnet from the dropdown menu, or leave it on No preference.

    • Firewall (security groups): Create a new security group or select an existing one.

    Configure storage section:

    • Set the size of the storage volume in gigabytes. The minimum value is 450 GB.

    • Select a root volume type from the dropdown menu.

  6. We strongly recommend setting up the connection to your Bitrise workspace during instance creation. This requires adding User data scripts in the Advanced details section: Using the AWS Secret Manager.

    Troubleshooting connection issues

    If you encounter problems with the connection after launching the instance, try connecting to the instance via SSH and troubleshooting the commands one by one: Troubleshooting the instance connection.

    You can learn more about user data in the AWS documentation: User data and the console.

  7. You can also set shell scripts or other custom data in the User data section. You can learn more about user data in the AWS documentation: User data and the console.

    In the Advanced options for EC2 instances section, you can find recommendations for optimizing your instance with user data:

  8. Click Launch instance.

    The launch can take up to 10-15 minutes. You will see system status checks and instance status checks: once the instance is ready, both checks will be green.

    aws-status-check.png
In this section: