From e60b19e53fbcce292b6ab0ecbe1a59c0b09119e4 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Mon, 28 Mar 2016 16:58:03 +0300 Subject: [PATCH] Refactor docs --- docs/faq/README.md | 42 ++++++++++++++++++++------------ docs/install/docker.md | 7 +++--- docs/install/freebsd.md | 7 +++--- docs/install/linux-manually.md | 3 ++- docs/install/linux-repository.md | 3 ++- docs/install/osx.md | 38 +++++++++++++++++------------ docs/install/windows.md | 3 ++- 7 files changed, 63 insertions(+), 40 deletions(-) diff --git a/docs/faq/README.md b/docs/faq/README.md index d03298c65..d5e998b20 100644 --- a/docs/faq/README.md +++ b/docs/faq/README.md @@ -128,30 +128,39 @@ See [an example of a user issue][1105]. [recipes]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server [1105]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/issues/1105 -## 11. Runner cannot be installed on OSX, because of `"launchctl" failed: exit status 112, Could not find domain for`: +## 11. `"launchctl" failed: exit status 112, Could not find domain for` -Make sure that you manage GitLab Runner service from the GUI Terminal application, not the SSH connection. +This message may occur when you try to install GitLab Runner on OSX. Make sure +that you manage GitLab Runner service from the GUI Terminal application, not +the SSH connection. -## 12. Runner is stuck on `Failed to authorize rights (0x1) with status: -60007.` when using OSX: +## 12. `Failed to authorize rights (0x1) with status: -60007.` -There are two problems why this happens: -1. Make sure that your user can do UI interactions. +If your Runner is stuck on the above message when using OSX, there are two +problems why this happens: - ``` +1. Make sure that your user can perform UI interactions: + + ```bash DevToolsSecurity -enable sudo security authorizationdb remove system.privilege.taskport is-developer ``` - + The first command enables access to developer tools for your user. - - Second command allows the user, member of developer group to do UI interactions, ex. run iOS simulator. + The second command allows the user who is member of the developer group to + do UI interactions, e.g., run the iOS simulator. + + --- -2. Make sure that your runner service doesn't use `SessionCreate = true`. -Previously when running GitLab Runner as an service we were creating the `LaunchAgents` with `SessionCreate`. -At that point (`Mavericks`) it was the only solution to make Code Signing work, -but recently with introduction of `El Capitan` OSX introduced a lot of new security features which did change this behaviour. -Since GitLab Runner 1.1 when creating a `LaunchAgent` we don't set the `SessionCreate`. -However, in order to upgrade you need to manually reinstall the `LaunchAgent` script: +2. Make sure that your Runner service doesn't use `SessionCreate = true`. + Previously, when running GitLab Runner as a service, we were creating + `LaunchAgents` with `SessionCreate`. At that point (**Mavericks**), this was + the only solution to make Code Signing work. That changed recently with + **OSX El Capitan** which introduced a lot of new security features that + altered this behavior. + Since GitLab Runner 1.1, when creating a `LaunchAgent`, we don't set + `SessionCreate`. However, in order to upgrade, you need to manually + reinstall the `LaunchAgent` script: ``` gitlab-ci-multi-runner uninstall @@ -159,4 +168,5 @@ However, in order to upgrade you need to manually reinstall the `LaunchAgent` sc gitlab-ci-multi-runner start ``` - Then you can verify that `~/Library/LaunchAgents/gitlab-runner.plist` have `SessionCreate` set to `false`. + Then you can verify that `~/Library/LaunchAgents/gitlab-runner.plist` has + `SessionCreate` set to `false`. diff --git a/docs/install/docker.md b/docs/install/docker.md index 90817a676..5583e2446 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -62,7 +62,8 @@ running already the config should be automatically reloaded! The runner should is started already and you are ready to build your projects! -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. ### Update @@ -114,7 +115,7 @@ gitlab/gitlab-runner latest 3e8077e209f5 13 hours ago gitlab/gitlab-runner alpine 7c431ac8f30f 13 hours ago 25.98 MB ``` -**Alpine Linux image is designed to use only Docker as the method of spawning runners.** +**Alpine Linux image is designed to use only Docker as the method of spawning runners.** The original `gitlab/gitlab-runner:latest` is based on Ubuntu 14.04 LTS. @@ -138,6 +139,6 @@ Install the `selinux-dockersock` and to resolve the issue: https://github.com/dp -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \ gitlab/gitlab-runner:latest ``` - + More information about the cause and resolution can be found here: http://www.projectatomic.io/blog/2015/06/using-volumes-with-docker-can-cause-problems-with-selinux/ diff --git a/docs/install/freebsd.md b/docs/install/freebsd.md index a7eb11dc0..a812b7426 100644 --- a/docs/install/freebsd.md +++ b/docs/install/freebsd.md @@ -24,7 +24,7 @@ Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/ci): Please enter the gitlab-ci token for this runner: Please enter the gitlab-ci description for this runner: -[name]: +[name]: Please enter the gitlab-ci tags for this runner (comma separated): Registering runner... succeeded @@ -43,5 +43,6 @@ gitlab-ci-multi-runner run Voila! Runner is currently running, but it will not start automatically after system reboot because BSD startup service is not supported. **The FreeBSD version is also available from [Bleeding edge](bleeding-edge.md)** - -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. + +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. diff --git a/docs/install/linux-manually.md b/docs/install/linux-manually.md index 5489e242f..48a2f32d1 100644 --- a/docs/install/linux-manually.md +++ b/docs/install/linux-manually.md @@ -67,4 +67,5 @@ Start the service: sudo gitlab-ci-multi-runner start ``` -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. diff --git a/docs/install/linux-repository.md b/docs/install/linux-repository.md index a4dc1cd8a..70dc7b42a 100644 --- a/docs/install/linux-repository.md +++ b/docs/install/linux-repository.md @@ -50,7 +50,8 @@ running already the config should be automatically reloaded! The runner should be started already and you are ready to build your projects! -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. ### Update diff --git a/docs/install/osx.md b/docs/install/osx.md index 09f6383dc..d26237290 100644 --- a/docs/install/osx.md +++ b/docs/install/osx.md @@ -71,32 +71,40 @@ Start the service: gitlab-ci-multi-runner start ``` -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. ### Limitations on OSX -Currently the only proven to work mode for OSX is running service in user-mode. +>**Note:** +The service needs to be installed from the Terminal by running its GUI +interface as your current user. Only then will you be able to manage the service. -**The service needs to be installed from Terminal running GUI interface as your user. -Only then you will be able to manage the service.** +Currently, the only proven to work mode for OSX is running service in user-mode. -Since the service will be running only when the user is logged in you should enable auto-logging on your OSX machine. +Since the service will be running only when the user is logged in, you should +enable auto-logging on your OSX machine. -The service will be launched as one of `LaunchAgents`. -By using `LaunchAgents` the builds will be able to do UI interactions, -making it possible to run and test on iOS simulator and also do process instrumentations. +The service will be launched as one of `LaunchAgents`. By using `LaunchAgents`, +the builds will be able to do UI interactions, making it possible to run and +test on the iOS simulator. -Worth to note is that OSX also have the `LaunchDaemons`, the services running completely in background. -The `LaunchDaemons` are run on system startup, but they don't have the same access to UI interactions as `LaunchAgents`. -You can try to run service as `LaunchDaemon`, but this mode of operation as of now is not supported. +It's worth noting that OSX also has `LaunchDaemons`, the services running +completely in background. `LaunchDaemons` are run on system startup, but they +don't have the same access to UI interactions as `LaunchAgents`. You can try to +run the Runner's service as `LaunchDaemon`, but this mode of operation is not +currently supported. -You can verify that runner created service configuration after the executing `install` command -by checking the `~user/Library/LaunchAgents/gitlab-runner.plist` file. +You can verify that the Runner created the service configuration file after +executing the `install` command, by checking the +`~user/Library/LaunchAgents/gitlab-runner.plist` file. ### Upgrade the service file -In order to upgrade the `LaunchAgent` configuration you need to uninstall and install the service: -``` +In order to upgrade the `LaunchAgent` configuration, you need to uninstall and +install the service: + +```bash gitlab-ci-multi-runner uninstall gitlab-ci-multi-runner install gitlab-ci-multi-runner start diff --git a/docs/install/windows.md b/docs/install/windows.md index 0ac2dba22..cbc105fce 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -60,7 +60,8 @@ Start service: gitlab-ci-multi-runner start ``` -Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. +Make sure that you read the [FAQ](../faq/README.md) section which describes +some of the most common problems with GitLab Runner. [x86]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-386.exe [amd64]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-amd64.exe -- GitLab