diff --git a/ACTIONS.md b/ACTIONS.md new file mode 100644 index 0000000000000..cc145291abe09 --- /dev/null +++ b/ACTIONS.md @@ -0,0 +1,178 @@ +# GitHub Actions setup + +Quarkus is built using GitHub Actions, with a mix of hosted and self-hosted runners. + +## Setting up a new self-hosted runner on Mac M1 + + +### Non-root user + +GitHub Actions should not run with administrator privileges, so will need to be run in a dedicated account. +Make an account for the actions runner. The steps below assume the account has the name `githubactions`. +It's usually easiest to do account creation in the GUI, via a VNC connection. Users are managed in +the **Users and Groups** section of the Settings app. + +*Grant administrator privileges to the account* (we will remove them later). + + +### System utilities + +As administrator, install homebrew. +```shell +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +Install build and container utilities: + +```bash +brew install mvn +brew install gradle +brew install podman +``` + +### Podman setup + +Podman needs some [extra configuration](https://quarkus.io/guides/podman) to work with test containers and dev services. + +Now log in to the account you created to run the actions. +As the `githubactions` user (but with administrator privileges) + +```bash +PODMAN_VERSION=`podman -v | sed 's/[a-zA-Z ]*//'` +sudo /opt/homebrew/Cellar/podman/$PODMAN_VERSION/bin/podman-mac-helper install +``` +The podman helper install seems to be per-user, but it needs to be done with administrator privileges. + +Again as the `githubactions` user, edit ~/.testcontainers.properties and add the following line: `ryuk.container.privileged=true` + +```bash +echo "ryuk.container.privileged=true" >> ~/.testcontainers.properties +``` + +```bash +podman machine set --rootful +podman machine start +``` + +Finally, on ARM, an [extra step](https://edofic.com/posts/2021-09-12-podman-m1-amd64) is required to make AMD64 images work: + +```bash +podman machine ssh +sudo -i +rpm-ostree install qemu-user-static +systemctl reboot +``` + +Now remove administrator privileges from the `githubactions` user. +As with the user creation, it's usually easiest to do this in the GUI. + +### Rosetta + +A fresh install of macOS will not have Rosetta installed, so Intel binaries cannot run. Fix this by running: + +```bash +softwareupdate --install-rosetta --agree-to-license +``` +### Stand up the actions runner + +#### Download the runner scripts + +GitHub provides an installation package of customised runner scripts for each repository. +Follow [the instructions](https://docs.github.com/en/actions/hosting-your-own-runners/adding-self-hosted-runners) +to install the scripts for the repository to be built. + +Choose the default group, a descriptive name, and the default work folder. Add a label `macos-arm64-latest`. +If you forget the label, it will need to be added [through the UI](https://docs.github.com/en/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners). + + +#### Cleanup and setup logic + +Self-hosted runners do not run on ephemeral hardware, and so workflow runs may need to clean up. +In this case, the main cleanup is a fresh workspace checkout, to ensure `git remote add` in the workflow step does not fail with `error: remote quarkusio already exists`.: + +(If the machine crashes, cleanup will not run, and the next run may fail. +If this becomes a common issue, we can update the workflow to run `git remote show quarkusio &> /dev/null || git remote add quarkusio https://github.com/quarkusio/quarkus.git`.) + +We also need to start a podman machine before the job if one is not already running. + +To create cleanup and setup scripts and hooks, run: + +```bash +echo "rm -rf /Users/githubactions/actions-runner/_work" > /Users/githubactions/runner-cleanup.sh +echo "podman machine info | grep Running || podman machine start" >> /Users/githubactions/podman-start.sh +chmod a+x /Users/githubactions/runner-cleanup.sh +echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/Users/githubactions/runner-cleanup.sh >> .env +echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/Users/githubactions/podman-start.sh >> .env +``` + + +In the same script, we also ensure that the podman machine is running before jobs execute. + +#### Start the runner + +To test the runner, run + +`run.sh` + +Once you're happy the runner is processing builds correctly, it's time to create it as a daemon. + +### Start the service on reboot + +Note that GitHub have scripts for this, but theirs run as LaunchAgents, not LaunchDaemons. +LaunchAgents run when a user logs in, and LaunchDaemons run on boot, so the daemon option seems preferable. + + +As administrator, `sudo vi /Library/LaunchDaemons/actions.runner.quarkusio-quarkus.macstadium-m1.plist`. + +Then add the following: + +```xml + + + + + Label + actions.runner.quarkusio-quarkus.macstadium-m1 + + RunAtLoad + + + KeepAlive + + + UserName + githubactions + + ProgramArguments + + /Users/githubactions/actions-runner/runsvc.sh + + + WorkingDirectory + /Users/githubactions/actions-runner + + StandardOutPath + /tmp/github.runner.plist.stdout + StandardErrorPath + /tmp/github.runner.plist.stderr + + EnvironmentVariables + + ACTIONS_RUNNER_SVC + 1 + + ProcessType + Interactive + SessionCreate + + + +``` + +Finally, run + +```shell +sudo launchctl load -w /Library/LaunchDaemons/github.runner.startup.plist +``` + +You can check the logs in `/tmp/github.runner.plist.stdout` to confirm everything is working. \ No newline at end of file diff --git a/docs/src/main/asciidoc/podman.adoc b/docs/src/main/asciidoc/podman.adoc index eb0dd433fff02..3527200907cb7 100644 --- a/docs/src/main/asciidoc/podman.adoc +++ b/docs/src/main/asciidoc/podman.adoc @@ -26,7 +26,8 @@ Once you have set up `brew`, you can use the `brew install` command to install P brew install podman brew install docker-compose podman machine init -v $HOME:$HOME -sudo /opt/homebrew/Cellar/podman/4.0.3/bin/podman-mac-helper install +PODMAN_VERSION=`podman -v | sed 's/[a-zA-Z ]*//'` +sudo /opt/homebrew/Cellar/podman/$PODMAN_VERSION/bin/podman-mac-helper install podman machine set --rootful podman machine start alias docker='podman'