{"id":15026047,"url":"https://github.com/davewoodcom/otago","last_synced_at":"2025-04-09T20:04:38.964Z","repository":{"id":146130795,"uuid":"234889385","full_name":"DaveWoodCom/OTAgo","owner":"DaveWoodCom","description":"An OTA App Distribution System for iOS and Android apps","archived":false,"fork":false,"pushed_at":"2021-09-04T04:46:08.000Z","size":205,"stargazers_count":24,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T20:04:31.241Z","etag":null,"topics":["android","apk","app","apple","appstore","distribution","ios","ota","otago","php","php7","php72"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaveWoodCom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-19T11:33:11.000Z","updated_at":"2025-01-24T17:51:31.000Z","dependencies_parsed_at":"2023-06-02T09:00:26.613Z","dependency_job_id":null,"html_url":"https://github.com/DaveWoodCom/OTAgo","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveWoodCom%2FOTAgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveWoodCom%2FOTAgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveWoodCom%2FOTAgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaveWoodCom%2FOTAgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaveWoodCom","download_url":"https://codeload.github.com/DaveWoodCom/OTAgo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103868,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","apk","app","apple","appstore","distribution","ios","ota","otago","php","php7","php72"],"created_at":"2024-09-24T20:03:37.084Z","updated_at":"2025-04-09T20:04:38.955Z","avatar_url":"https://github.com/DaveWoodCom.png","language":"PHP","funding_links":["https://www.patreon.com/DaveWoodX"],"categories":[],"sub_categories":[],"readme":"\n![OTAgo][otago-logo]\n\n[![badge-language]][php.net]\n[![badge-license]][license]\n\n[![badge-mastodon]][mastodon-davewoodx]\n[![badge-twitter]][twitter-davewoodx]\n\n[![badge-sponsors]][cerebral-gardens]\n[![badge-patreon]][patreon-davewoodx]\n\n## About\n\nOTAgo is an OTA app distribution system that allows you and your users to securely install their iOS and/or Android apps over the air (OTA). iOS distribution uses Apple's officially supported method [documented here](https://support.apple.com/en-ca/guide/deployment-reference-ios/apda0e3426d7/web).\n\n## Communication\n\n* If you need help, use [Stack Overflow][stackoverflow] (Tag '[otago][stackoverflow]').\n* If you'd like to ask a general question, use [Stack Overflow][stackoverflow].\n* If you've found a bug, open an issue.\n* If you have a feature request, open an issue.\n* If you want to contribute, submit a pull request.\n* If you use OTAgo, please Star the project on [GitHub][github-otago]\n\n## Requirements\n\n* HTTPS enabled web server ([nginx][nginx] or [Apache][apache] recommended)\n* PHP 7.x\n* binary files to distribute (at least one of):\n    * .ipa file (signed with an ad-hoc or enterprise distribution profile)\n    * .apk file (fat file, not an app bundle, or an apk split per abi)\n\n## How to Use\n\nClone the repo into a folder accessible via HTTPS. You must use HTTPS with a valid (not self-signed) SSL/TLS certificate. (I recommend [Let's Encrypt][letsencrypt]). \n\n### Configuration\n\nCopy the file `configuration.default.php` to `configuration.php`. You'll configure the system by editing the copy. You should back this file up as it's excluded from the git repository by default.\n\nConfiguration variables:\n\n* `$baseURL` -\u003e During an OTA installation, some files need to be referenced by their full URL. OTAgo uses a default value for the baseURL, however it's not likely going to match your actual URL, so you'll want to set this directly.\n* `$authFile` -\u003e filename of a `.php` file to handle the authentication (see below).\n* `$webTemplate` -\u003e the `.html` template to be displayed to the user before they install the app.\n* `$installURLPlacehHolder` -\u003e a placeholder token for the link that will start the app installation.\n\n* `$enableIOS` -\u003e set to true if you support iOS/iPadOS, then configure the iOS specific variables:\n    * `$manifestTemplate` -\u003e the `manifest.plist` template used to install the app.\n    * `$ipaURLPlacehHolder` -\u003e a placeholder token in the above manifest template file where the authenticated URL will be swapped in.\n    * `$ipaFile` -\u003e the `.ipa` file for iOS/iPadOS distribution.\n\n* `$enableAndroid` -\u003e set to true if you support Android, then configure the Android specific variables:\n    * `$apkFile` -\u003e the `.apk` file for Android distribution.\n\nThe authentication system used may have additional options, examples are in the `configuration.default.php` file.\n\nThe files above do not need to be located in a publicly accessible folder, their contents will be served by the OTAgo scripts.\n\n### AuthFile\n\nThe `$authFile` variable above needs to name a file that can be included by the OTAgo scripts. This allows you to sub in different methods of authentication, a simple list of username/passwords, connect to an external database, or use OAuth. Currently OTAgo includes two authentication options: \n\n##### None\n\nThis effectively removes authentication, and allows anyone to install the app. Of course, iOS will require the `.ipa` file to be signed with a profile that includes the required device ids, or optionally, an Enterprise certificate.\n\nTo disable authentication, set `$authFile = 'auth/none/none.php';` in the `configuration.php` file.\n\n##### Simple Auth\n\nSimple Auth allows you to create a simple list of username/passwords. Add them to the `$users` array in the `configuration.php` file.\n\nThere are a two other options you should set:\n\n`$simpleAuthTempDirectory`: a temporary directory where the authentication system can store access tokens (the web server needs write permission). Our example configuration uses `/tmp`, but it would be more secure to use a folder that is inaccessible to other users on the system.  \n\n`$simpleAuthTokenLifetime`: the number of seconds a token should be valid. By default we set it to 3600 seconds (1 hour), which should be fine for most cases.  \n\n##### Custom Authentication\n\nIf you wish to use another authentication method, you need to create an alternate authFile that includes the following methods:\n\n\n```php\n\tfunction isValidUser()\n```\n\nThis takes no parameters and must determine if the current user is valid or not. Return `true` if they the user is authorized to install the app.\n\n\n```php\n\tfunction queryStringAuthParameters()\n```\n\nThis method takes no arguments. It must return an associated array with name/value pairs to be appended to OTAgo URLs. This is how OTAgo will pass the authentication through to the manifest and ipa URLs.\n\n```php\n\tfunction requestAuthentication()\n```\n\nThis method takes no arguments, and returns no value. It must send whatever is needed to the client to deny access and request authorization. Like the version in the `simpleAuth.php` file, you can call `requestBasicAuthentication()` to trigger a BASIC authentication request.\n\n\n### Templates\n\nThe `$webTemplate` file needs to be an HTML file that will be displayed to the user. This can be basic HTML with a single link, or more complicated with details about the app with instructions for the user on how to install it (trusting the Enterprise certificate for example). The template file itself does not need to be in a publicly accessible folder, however any files the page links to, images, stylesheets, etc must be. The `$webTemplate` file should have at least one link with the `href` set to the `$installURLPlacehHolder` (`{{InstallURL}}` in our demo). That link will start the install process when the user taps it.\n\nThe `$manifestTemplate` file needs to be a valid `manifest.plist` file (see [Apple's documentation](https://support.apple.com/en-ca/guide/deployment-reference-ios/apd11fd167c4/web) for specifics), but instead of specifying the URL for the `.ipa` file, use the `$ipaURLPlacehHolder` placeholder (`{{IPAURL}}` in our demo). The authenticated URL will be substituted into the `.plist` file before it's sent to the user's device.\n\n### Contributing\n\nOTAgo can only exist with support from the community. There are many ways you can help continue to make it great.\n\n* Star the project on [GitHub][github-otago].  \n* Report issues/bugs you find.  \n* Suggest features.  \n* Submit pull requests.  \n* Download and install one of my apps: [https://www.cerebralgardens.com/apps/][cerebral-gardens-apps]. Try my newest app: [All the Rings][all-the-rings].  \n* You can visit my [Patreon][patreon-davewoodx] and contribute financially.  \n\n**Note**: when submitting a pull request, please use lots of small commits verses one huge commit. It makes it much easier to merge in when there are several pull requests that need to be combined for a new version.\n\n## Why's the project called OTAgo, and why is a koala involved?\n\nI'm personally very concerned about the planet and the current Climate Emergency we're in. During the time I've been developing this project, there have been massive bushfires in Australia. I wanted to name the project after the situation. There are several places in Australia named `Otago` which has an obvious link to `OTA`; it felt like a perfect name. The koala is a reference to the hundreds of thousands of animals killed during the fires.\n\nMy thanks to [Freepik](https://www.flaticon.com/authors/freepik) at [flaticon.com](https://www.flaticon.com/) for providing the [koala](https://www.flaticon.com/free-icon/koala_2424348) used in the OTAgo logo.\n\n\n\n\n[otago-logo]: https://github.com/DaveWoodCom/OTAgo/raw/main/logo.png\n[php.net]: https://php.net/\n[license]: https://github.com/DaveWoodCom/OTAgo/blob/main/LICENSE\n\n[mastodon-davewoodx]: https://mastodon.social/@davewoodx\n[twitter-davewoodx]: https://twitter.com/davewoodx\n\n[stackoverflow]: https://stackoverflow.com/questions/tagged/otago\n\n[cerebral-gardens]: https://www.cerebralgardens.com/\n[cerebral-gardens-apps]: https://www.cerebralgardens.com/apps/\n[all-the-rings]: https://alltherings.fit/?s=GH4\n[patreon-davewoodx]: https://www.patreon.com/DaveWoodX\n\n[badge-language]: https://img.shields.io/badge/PHP-7.x-blue.svg?style=flat\n[badge-license]: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg?style=flat\n\n[badge-sponsors]: https://img.shields.io/badge/Sponsors-Cerebral%20Gardens-orange.svg?style=flat\n[badge-mastodon]: https://img.shields.io/badge/Mastodon-DaveWoodX-606A84.svg?style=flat\n[badge-twitter]: https://img.shields.io/twitter/follow/DaveWoodX.svg?style=social\n[badge-patreon]: https://img.shields.io/badge/Patreon-DaveWoodX-F96854.svg?style=flat\n\n[github-otago]: https://github.com/DaveWoodCom/OTAgo\n[nginx]: https://nginx.org/\n[apache]: https://httpd.apache.org/\n[letsencrypt]: https://letsencrypt.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavewoodcom%2Fotago","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavewoodcom%2Fotago","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavewoodcom%2Fotago/lists"}