30 Jan 2024
Need to distribute your signed iOS IPA builds? We’ve got you covered.
In this post, we will guide you on how to distribute and install non-market iOS IPA applications over the air (OTA) using a simple, self-hosted server. This method does not require TestFlight, the official App Store or tools like Expo, making it a great solution for internal builds and testing.
Why not use Expo you might ask? Expo is an excellent platform, and we do use it a lot, but sometimes you just want to distribute an app without going through it. This might be the case for many reasons from testing unreviewed code, to avoid necessary costs/flooding the queue system. After all, their pricing is quite steep, currently, they charge $200/month per concurrency slot plus up to 4$ per build (depending on the application size, usually 2$).
To solve this, we created a self-hosted project to help anyone distribute their apps: ios-ipa-app-distribution-server. Let's jump into it and show how it works!
An iOS .ipa
app build signed for your device (that should already have the development mode activated).
Docker installed on your machine or server.
First, we need to run the server using Docker. Open your terminal and run the following command:
docker run \
-p 8000:8000 \
-v ipa-uploads:/uploads \
-it ghcr.io/significa/ipa-app-distribution-server
This command will start the application and expose it on port 8000. You can deploy this image to your server and put it behind a custom domain. This way you could distribute apps to users outside your network. For now, we will just use your internal IP. To do that retrieve your internal IP with ifconfig
on Linux and Mac, or Windows with ipconfig
.
Access http://YOUR_IP_OR_HOSTNAME:8000/docs
replacing YOUR_IP_OR_HOSTNAME
with your internal IP or public hostname accessible from your iOS device.
Use the default token secret
or the one you have configured in the UPLOADS_SECRET_AUTH_TOKEN
env var and pick the IPA build file you wish to distribute.
Click "Execute" and assuming everything went smoothly it will return a link to the installation page.
Open the link returned by the previous command in a web browser. You will see a minimalistic installation page with a QR code.
Scan the QR code with an iOS device. This will prompt the device to install the app.
And that's it! You have successfully distributed and installed a non-market iOS IPA application over the air using a simple, self-hosted server.
Now, you probably want to automate the process of creating an installation page. To do this, upload your IPA build with the following command:
curl -X "POST" \
"http://YOUR_IP_OR_HOSTNAME:8000/upload" \
-H "Accept: application/json" \
-H "X-Auth-Token: secret" \
-H "Content-Type: multipart/form-data" \
-F "ipa_file=@your-app-build.ipa"
Replace your-app-build.ipa
with the path to your .ipa
file.
By default, the project stores the data in the file system for a production-ready environment. You might wish to store data in a cloud-storage bucket like AWS S3:
Create a S3 bucket (private: no public access).
Create an IAM user with the following permissions (ex: inline):
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::YOUR_BUCKET_NAME",
"arn:aws:s3:::YOUR_BUCKET_NAME/*"
]
}
]
}
Create access keys for your IAM user.
Configure the IPA server environment variables:
For security reasons, remember to change the UPLOADS_SECRET_AUTH_TOKEN
in a production environment. Otherwise, anyone can upload files to your server.
That's it! We hope this is useful.
For more details, refer to the project's documentation.
Francisco Marques
CTO
Francisco is the CTO at Significa but more importantly, he’s our office keeper. The Hagrid of Torrinha 154. He always keeps a hammer and a handful of nails by his desk, just in case.
Elisa Sampaio
Designer
Alec Norton
Operations Manager
13 February 2024
How we increased employee engagement at Significa.