Please note this information is for contributors with direct access to the build host. In case you would like to contribute to AutoPkg please read our contribution guide.
Orchard's autopkg configuration is hosted on a Mac Pro with a large local storage array. The buildhost has a local user 'autopkg' whose $HOME is in /srv/autopkg/. Because autopkg does not work well in multi-user environments (each user would need the same set of recipe repos imported and cannot share preferences), the autopkg user has all the defaults set necessary to build our software set, and it is necessary to switch to this user by prefixing $ sudo -u autopkg to issue any autopkg commands.
All recipes should be overridden locally, even if you have written a recipe yourself. Recipes should be written for the wider autopkg community and any local standards/customisations should be done in an override.
The directory /srv/autopkg/RecipeOverrides/ is a git clone of the ox-it orchard-recipe-overrides repo on Github N.B. this repository is currently private, although we hope to make it public once certain sensitive information has been removed.
Once you have written a recipe, or imported a recipe repo containing a munki recipe you would like to use, you should issue
$ sudo -u autopkg autopkg make-override <RecipeName>.munki
This will create a recipe at /srv/autopkg/RecipeOverrides/<RecipeName>.munki.recipe which you must then edit according to the standards set out here
To test your override issue $ sudo -u autopkg autopkg run -vv <RecipeName>.munki. You should see your app downloaded, optionally packaged, and then imported into Munki with a useful version number, along with the input and output of each processor step. If anything goes wrong with this process you will probably want to delete the package and associated pkginfo from the munki repo before making changes and trying again.
Note this only imports the item into the Munki catalogs and to have it appear in Orchard Software Centre it must be added to a manifest. See the Munki page for more info.
When you are satisfied with your edits, add the file to the next commit by issuing $ git add <filename> and then commit it to the repository with $ git commit -m "Commit message". Once you have finished creating or editing recipes you should then push them upstream with $ git push origin master which will prompt you for your github username and password.
Automatic runs of building the software set are done via a LaunchDaemon /Library/LaunchDaemons/uk.ac.ox.autopkg-rebuild.plist which runs the script /srv/autopkg/bin/autopkg-rebuild.sh at 8pm each night. This goes through the files in /srv/autopkg/BuildRecipes and performs autopkg check and then autopkg run on each filename if new downloads are detected. In order to add your newly created override to the build run, you should create a symlink to the override e.g.:
$ cd /srv/autopkg/BuildRecipes $ sudo -u autopkg ln -s ../RecipeOverrides/<RecipeName> .
autopkg-build.sh logs to /srv/autopkg/Library/Logs}. Errors are also emailed to EDMS Teams. All errors of an unknown cause should be investigated.
Conversely, if you want to stop automatically building a recipe, delete the symlink. To see what is available in RecipeOverrides but not being run from BuildRecipes you can do $ diff -r /srv/autopkg/BuildRecipes /srv/autopkg/RecipeOverrides Note that there may be good reasons that an app is not being built automatically, always check with the rest of the team if in doubt.
Sometimes, due to issues upstream, it is necessary to pause building of packages (where for instance the upstream build is failing, and there is no quick fix). In these cases you should move the recipe into directory OutOfAutoBuild:
$ cd /srv/autopkg $ sudo -u autopkg mv /srv/autopkg/BuildRecipes/<RecipeName> /srv/autopkg/OutOfAutoBuild
and do the reverse once the upstream issue is fixed.
