EAS on-infra

A self-hosted EAS build CLI designed to offload builds to a remote system.

This is a tool designed to wrap the EAS CLI on your own hardware, and expose a set of endpoints to enable functionality such as building.

Project status

This project is currently in beta status. It should mostly work, but there may be bugs.

Requirements - Hardware

Your requirements may vary, but I recommend the following setup if you intend to build iOS apps (can also build Android apps):

• Mac Mini featuring at least an M1 chip
  • Note: The M1 is likely to be deprecated for updates in a few years, so a more recent model such as M4 or M5 is advised for longer-term support
• 32GB RAM minimum (24GB might be manageable, but I don't recommend less than 32GB)
• 1TB internal storage recommended (512GB may be sufficient)

If you intend to run this for many projects, create many builds, or you're serving a business or office environment, I recommend the following additional:

• An external storage drive, 2TB or greater

If you're only building Android apps, you should be able to run this on a Windows or Linux system, but these setups are not tested.

Requirements - Software (build server)

The following tools are required to be installed and configured on the build server. The list below is assuming you're using a Mac as the build server:

• NodeJS
  • I recommend usingNVM (Node Version Manager) as this can help keep your version up to date
  • Make sure to nvm install (followed by a version number) after installing NVM
• EAS CLI (npm install -g eas-cli)
• Homebrew (tooling installation) (/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")
• Fastlane (iOS builds) (brew install fastlane)
• Cocoapods (iOS builds) (brew install cocoapods)
• Java (Android builds) (brew install openjdk@17)
• Android Studio (Android builds) (Download here: https://developer.android.com/studio )

Note: The commands above may not be the most up-to-date when you read this. For example, Java/OpenJDK might need a newer version. I recommend Googling to check for the latest info.

You must ensure that you go through any necessary configuration for these tools before attempting to build. For example, with Android Studio, you will likely have to install the build tools from within Android studio, and perhaps agree to licenses. You also probably need to set things like ANDROID_HOME variables - Google how to do this because it's outside the scope of this readme.

Additional tooling below is required only if you need third-party installers (see official docs for most recent commands):

• Yarn (npm install -g yarn)
• Bun (curl -fsSL https://bun.com/install | bash)
• Pnpm (npm install -g pnpm@latest-10 or brew install pnpm)

For convenience, I also recommend the following if you're on a Mac:

• XCodes - This makes it easier to manage Xcode versions and keep up to date with the latest version

Once you've configured the tooling, I recommend trying to run a build using a locally cloned version of a project (or creating a fresh Expo project), as this can often help identify if there are configuration issues.

Project requirements

In order to create builds using this tool, you must ensure that your project is already configured with EAS, and that certificates and profiles have been provisioned. This is because this tool runs in non-interactive mode on the server.

You will also need to ensure you have create an EAS access token.

You will also need to create an env file of some sort in your project, as you will need to add your EAS access token to it. See below for more information.

Setup - Server

On the system which will be running the build, close this repo and run yarn from the directory to install dependencies. Alternatively, you can install it globally on the server with:

npm install -g @chronsyn/eas-on-infra

Note: If you choose to install it globally, you will not be able to make use of a .env file on the server, but you can still pass env variables to it using typical platform methods.

Then, create a .env file (or specify manually) with the following variables:

• PORT (number, which port the server will accept requests on, defaults to 3000 if not specified)
• SITE_BASE_URL (string/text, the URL where your builder is running. This could be the device IP if you don't have a domain setup for it)

Note: SITE_BASE_URL is currently only used to output a status URL, but the status URL itself isn't yet implemented. This will be added in a future version.

You can also specify the following optional fields:

• EXTRACT_DIRECTORY (string/text - the directory where files will be extracted - note: a unique subdirectory will be created for each upload)
• BINARY_OUTPUT_DIRECTORY (string/text - the directory where built app binaries will be output)
• UPLOAD_DIRECTORY (string/text - the directory where zip files will be uploaded)

By default, the extracted, builds, and uploads directories within this project will be used if any of the above aren't specified.

If you cloned the repo, run yarn start . Your server is now running and ready to start builds. Alternatively, run npx @chronsyn/eas-on-infra serve.

Setup - local system (e.g. your laptop where the code is available)

In this context, the local system would be any system where the Expo project code is available - for example, a laptop that is used to develop the code.

• Add your Expo access token to your dotenv file (ELB_EAS_ACCESS_TOKEN=<your access token>)
• Ensure you have configured your project to build (eas build:configure => eas build --profile <profile> --platform <platform>, then follow any instructions. You can cancel the process when you see 'Uploading to EAS' to prevent the build from running).

Then, run:

npx @chronsyn/eas-on-infra build --profile production --platform ios --config_file_path .env --build_server http://address-of-your-build-server

NPM / NPX might be prompt you to install the library - press y if you're happy to continue.

After that, your project will be zipped up (excluding node_modules), and sent to the build server.

Command flags

--profile

• Required: Yes
• What: A build profile which is specified in your eas.json file
• Note: In a future version, you will be able to define specific profile names which are allowed

--platform

• Required: Yes
• What: Which platform are you building for
• Valid options: ios, android
• Note: The all option is not supported, but you may be able to run both Android and iOS builds at the same time

--config_file_path

• Required: No
• What: The filename (not the file path) to the env file you want to use with the project. For example, .env, .env.local, etc.
• Why: In case you want to use a specific config file with the build - useful to create bespoke builds that aren't linked to standard environments.
• Default value: None
• Note: The env file you want to include should be located in the root of the project. Other .env files will be excluded from the bundle. If this flag is not specified, all .env files will be excluded.

--installer

• Required: No
• What: Which tool you want to use to install the project dependencies
• Valid options: npm, yarn, bun, pnpm
• Default value: npm
• Note: This will run the appropriate installation command for the tool you specify

--build_server

• Required: Yes
• What: The base URL of your build server
• Example: if your build server is running at 192.168.1.25 on port 3000, this would be http://192.168.1.25:3000

Bug reports

As this project is based primarily around EAS CLI, issues you experience can often be resolved in the same way you'd resolve them if using EAS locally or on the official Expo EAS servers.

Bug reports are still accepted, but the following types of issues will be closed (list is non-exhaustive):

• 'Will this run on ?' (Try it and find out for yourself)
• 'I received help!' (Google the error message)
• 'It didn't use the latest CLI version!' (You're resposible for managing the infra and tooling)
• 'Where's the publish command?' (This isn't an update publishing server)
• Anything that's not explicitly related to this tool

If you experience issues:

• Scroll through the logs and read what it says
• Google error messages

Why build this?

I typically work across multiple systems with various different operating systems, with code stored on one central system, and using SSH to access it.

One problem is that if the central system isn't a mac, I can't build iOS apps due to Apple's restrictions and requirements. I felt it was time to resolve that issue, but without explicitly requiring me to host the projects on a mac.

So, say hello to 'EAS on-infra'.

How does it work?

It's really just a simple REST API with only a few endpoints. The /ingress POST endpoint accepts a zip file and some other fields.

The server extracts the zip, runs npm i to install dependencies for the project (can be customised to use yarn, bun, or pnpm), and then attempts to run the eas build command on the extracted files (along with some relevant flags, such as --profile, --platform, and most importantly --local and --non-interactive and --output).

What doesn't this tool do?

This tool does NOT do any of the following:

• OS system updates
• Core build tool updates (e.g. xcode, android studio)
• CLI updates (e.g. eas-cli)
• Bypass build requirements (e.g. iOS builds still require the server part of this tool to be run on a Mac)
• Make dinner

Issue debugging

The following info might be useful if you experience issues

• package.json was not found in the project directory* Make sure your project is initialised with git (git init), all files are added (git add .), and commited (git commit -m 'comment').

• iOS builds: Distribution certificate with fingerprint hasn't been imported successfully One possible solution