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. The process has three main phases but you can complete it in one sitting:

  1. Preparing your EC2 instance.

  2. Configuring the instance on AWS.

  3. Connecting the instance to your Bitrise workspace.

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

Preparing your EC2 instance

Mac instance

Linux instance

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

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

Configuring the instance

Mac instance

Linux instance

  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.

      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.

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

  2. Navigate to the EC2 Dashboard.

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

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

    aws-markplace-amis.png

  5. 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.

  6. 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. The subnet must be able to access the internet either via a NAT Gateway or an Internet Gateway.

    • 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.

Connecting the instance to your Bitrise Workspace

Mac bare metal instance

Mac virtualized instance

Linux instance

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

    • https://den.services.bitrise.io

    • https://build-log.services.bitrise.io

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

    Important

    When modifying the user data scripts for a macOS 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 --region ${Region} secretsmanager get-secret-value --secret-id MY_SECRET | jq -r '.SecretString')

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 instances section, you can find recommendations for optimizing your instance with user data:

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

    • https://den.services.bitrise.io

    • https://build-log.services.bitrise.io

  2. Modify the User data of the instance: add the command to launch the Bitrise runner, using the Secret you created in the AWS Secret Manager. You also need to provide the number of concurrencies and the stack you wish to run.

    Important

    When modifying the user data scripts for a macOS 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.

    You can get the list of available stacks with the following command:

    /opt/virtualization-cli/bin/virtualization-cli list

    The allowed values for your concurrency preference are 1 or 2.

    • With 1 CC, the runner will schedule 1 VM with 8 vCPU and 12 GB RAM.

    • With 2 CC, the runner will schedule 2 VMs with 4 vCPU and 6 GB RAM each.

    TOKEN=$(aws secretsmanager get-secret-value --secret-id MY_SECRET | jq  -r '.SecretString')
sudo sed -i '' 's/BITRISE_AGENT_CC/<YOUR_CONCURRENCY_PREFERENCE>/' /Users/ec2-user/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist
sudo sed -i '' 's/BITRISE_AGENT_STACK/<YOUR_DESIRED_STACK>/' /Users/ec2-user/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist
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 instances section, you can find recommendations for optimizing your instance with user data:

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

    • https://den.services.bitrise.io

    • https://build-log.services.bitrise.io

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

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

sudo sed -i “s/BITRISE_AGENT_TOKEN/$TOKEN/” /etc/systemd/system/bitrise-den-agent.service
sudo systemctl start bitrise-den-agent.service

  3. 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:

In this section: