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 Mac or Linux instance.

This document guides you through launching an instance on the Amazon EC2 console UI. The process has three main phases but you can complete it in one sitting:

  1. Preparing your EC2 Mac or Linux instance.
  2. Configuring the instance on AWS.
  3. Connecting the instance to your Bitrise workspace.

Preparing your EC2 Mac and Linux instanceClick to copy link​

  1. Configure a runner pool and copy the token required for authentication.
  2. Get the token from the process of adding the runner pool on Bitrise.
  3. Create an AWS Secrets Manager secret and store the token in the secret.
  4. Create an IAM role with permission to read the secret. You will need to attach it to the EC2 instance.
  5. Allocate a dedicated host on AWS. You will need the automatically generated host ID.

Configuring the instanceClick to copy link​

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

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

    aws-markplace-amis.png

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

  4. 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 GB.

      For the virtualized macOS AMI, we recommend 700GB with 1 VM per host and 1000GB with 2 VM per host.

      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.

Connecting the EC2 Mac or Linux instance to your Bitrise WorkspaceClick to copy link​

  1. Make sure that your instance can access the following endpoints:

  2. Modify the User data of the instance: add the command to launch the Bitrise runner, using the Secret you created in the AWS Secrets Manager:

    important

    When modifying the user data scripts for an EC2 Mac instance, make sure that there is no empty space before the start of the script. The first line should always be #!/bin/bash. If there is empty space before this line, the instance won't work.

    TOKEN=$(aws secretsmanager get-secret-value --secret-id MY_SECRET | jq -r '.SecretString | fromjson | .["MY_SECRET"]')

    sudo sed -i '' "s/BITRISE_AGENT_TOKEN/$TOKEN/" /Users/ec2-user/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist
    sudo launchctl load -w /Users/ec2-user/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist

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

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