docs(running renovate): rewrite (#21222)

Co-authored-by: Michael Kriese <michael.kriese@visualon.de>
Co-authored-by: Rhys Arkins <rhys@arkins.net>

docs/usage/getting-started/running.md

@@ -1,68 +1,94 @@
 # Running Renovate
 
-As a Renovate end user, there are two main categories of use:
+As end user, you can choose from these ways to run Renovate:
 
-- You self-host Renovate, e.g. by running the pre-built Docker image, or
+- You use the Mend Renovate app on GitHub, or
+- You self-host Renovate, for example by running the pre-built Docker image, or
 - Someone else is hosting Renovate, and you install/configure it for the repositories you choose
 
-If someone else is hosting Renovate for you, or you are using the Mend Renovate App on GitHub, then you can skip ahead to the [installing & onboarding](./installing-onboarding.md) page.
+If you're using the Mend Renovate App on GitHub, or if someone else is hosting Renovate for you, skip ahead to the [installing & onboarding](./installing-onboarding.md) page.
 
 ## Self-Hosting Renovate
 
-Self-hosting Renovate means that you are the "administrator" of the bot, which entails:
+When self-hosting Renovate you're the "administrator" of the bot, this means you:
 
-- You provide infrastructure for it to run on,
-- You provision its global config,
-- You ensure it's running regularly,
-- You ensure Renovate bot itself is updated
+- provide the infrastructure that Renovate runs on,
+- provision Renovate's global config,
+- make sure Renovate bot runs regularly,
+- make sure Renovate bot itself is updated
 
-Read our section on [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate bot.
+If you're self-hosting Renovate on Windows, read [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate bot.
 
 ### Available distributions
 
 #### npm package (CLI)
 
 Renovate's Open Source CLI is built and distributed as the npm package `renovate`.
-You can run this directly in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting.
-When you install Renovate from npm it naturally does not come bundled with any third-party tools or languages such as Ruby, Python, Composer, Bundler, Poetry, etc.
-If you need Renovate to support any non-npm lock files like Bundler then you'll need to make sure all required third-party tools are pre-installed in the same environment alongside Renovate before you run it.
+You can run this package in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting.
+
+When installing Renovate via npm you are responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc.
 
 The `renovate` npm package is compatible with all of Renovate's supported platforms.
 
-#### Docker image
+#### Docker images
+
+Renovate is also distributed as Docker images on Docker Hub (`renovate/renovate`) and GitHub container registry (`ghcr.io/renovatebot/renovate`).
+These Docker images work on all the hosting platforms that Renovate supports.
+
+You must run the Docker images in a `linux/amd64` container.
+We're working on `linux/arm64` container support.
+You can't run the Docker images in a Windows or macOS container.
+
+In general, you can run Renovate natively on Windows as long as you have all tools it will need (e.g. `npm`, `pipenv`, etc.) preinstalled before you run Renovate.
+
+There are two flavors:
+
+- The `-slim` image
+- The default "full" image, this is the image you'll get if you use the `latest` tag
 
-The `renovate` npm package is also distributed via pre-built Node.js images on Docker Hub (`renovate/renovate`).
+##### The slim image
 
-The `slim` image contains only Node.js so works if either:
+The `-slim` image only comes with the Node.js environment.
+By default, the image installs the required tools when needed.
+We recommend the `-slim` image for most users.
 
-- You do not require any additional package managers, or
-- You map the Docker socket into the container so that Renovate can dynamically invoke "sidecar" images when necessary
+If you want, you can map the Docker socket into the container so that Renovate can dynamically invoke "sidecar" images when needed.
+You'll need to set `binarySource=docker` for this to work.
+Read the [`binarySource` config option docs](../self-hosted-configuration.md/#binarysource) for more information.
 
-The "full" image (which `latest` defaults to) has every package manager which Renovate supports already preinstalled.
-This approach works best for many, but does have the following downsides:
+##### The default image
 
-- It only has _one_ version of each language/manager - usually the latest
-- It's several gigabytes in size
+The default image comes with most package managers that Renovate supports, but not _all_ package managers.
 
-The `renovate/renovate` Docker images are compatible with all of Renovate's supported platforms.
+You must set `binarySource=global`, if you don't then Renovate still installs the latest version of the tools or the requested version from the repository.
+Update your Docker images regularly to keep the pre-installed tools up-to-date.
+
+Renovate supports a persistent cache for downloaded tools, so that it only needs to unpack the tools on later runs.
+Use the [`containerbaseDir` config option](../self-hosted-configuration.md/#containerbasedir) to control where Renovate stores its containerbase cache.
+
+The default image is for users who don't want to download or install things at runtime.
+The default image has some downsides, because it:
+
+- Comes pre-installed with _one_ version of each language/manager - usually the latest
+- Weighs several gigabytes
 
 #### GitHub Action
 
-Renovate's npm tool is also provided as a pre-prepared GitHub Action on [`renovatebot/github-action`](https://github.com/renovatebot/github-action).
+Renovate's npm tool is also provided as a GitHub Action on [`renovatebot/github-action`](https://github.com/renovatebot/github-action).
 Details on how to use it can be found in the repository.
 
 #### GitLab Runner
 
 The Renovate team provide a ["Renovate Runner"](https://gitlab.com/renovate-bot/renovate-runner/) project to make it easier to run Renovate as a CI pipeline job.
-This supports both `gitlab.com` as well as self-hosted GitLab.
+This supports both `gitlab.com` and self-hosted GitLab.
 Details for how it works can be found in the project.
 
 #### Mend Renovate On-Premises
 
 Mend Renovate On-Premises (WSOP) started out as a commercial product "Renovate Pro", but was renamed and made free to use when Renovate became a part of Mend (formerly WhiteSource) in 2019.
-It is built similarly to the "full" Renovate image described above, but with these differences:
+It is built similarly to the default "full" Renovate image described above, but with these differences:
 
-- It is a stateful app and does not exit once it's processed all repositories
+- It is a stateful app and does not exit after processing all repositories
 - It is installed as an App on GitHub, and behaves similarly on GitLab - for example responding to webhooks
 - It includes a priority job queue which prioritizes events like merged PRs over scheduled jobs
 - It is released every 1-2 months in a slower, more stable cadence than Renovate OSS, which releases on every commit
@@ -81,7 +107,7 @@ Mend Remediate supports GitHub Enterprise Server, GitLab self-hosted, and Bitbuc
 #### Forking Renovate app
 
 "Forking Renovate" is the sister app to the Mend Renovate App on GitHub.com.
-The difference is that Forking Renovate does not require `write` permissions to create branches within the repo, and instead submits PRs from its own fork.
+The difference is that Forking Renovate does not need `write` permissions to create branches within the repo, and instead submits PRs from its own fork.
 Because of how it works, it functions on public repositories only and additionally cannot support `automerge` capabilities.
 
 [Install Forking Renovate from GitHub App](https://github.com/apps/forking-renovate).
@@ -94,43 +120,50 @@ Forking Renovate needs only `read` level access to the code of any repository it
 
 If you use Forking Renovate, you'll miss out on these features of the regular Renovate app:
 
-- Automerge is not supported
-- The `baseBranches` config option is not supported
-- The app dashboard (`app.renovatebot.com`) is currently not supported
+- Automerge
+- The `baseBranches` config option
+- The app dashboard (`app.renovatebot.com`)
 
 ### Hosting Renovate
 
-Once you have decided on a Renovate distribution, you need to decide where and how to run it.
+After deciding on a Renovate distribution, you need to decide where and how to run it.
 
 For the GitHub Action and GitLab Runner approaches, they will naturally run on their respective CI infrastructure.
 For the npm package approach or Docker images, you will need some form of VM or container infrastructure to run Renovate on.
 
-In all the above cases you will need to make sure that some form of cron-like capability exists to schedule when Renovate runs.
-In general we recommend to run Renovate hourly if possible.
+In all the above cases you must make sure that some form of cron-like capability exists to schedule when Renovate runs.
+We recommend that you run Renovate hourly, if possible.
 
-Mend Renovate On-Premises and Mend Remediate both run as long-lived containers so do not need any additional cron-like concept as it is built-in.
+Mend Renovate On-Premises and Mend Remediate both run as long-lived containers, so they do not need any additional cron-like concept as it is built-in.
 
 ### Global config
 
-Renovate's server-side/admin config is referred to as its "global" config, and can be specified using either a config file, environment variables, or CLI parameters.
+Renovate's server-side/admin config is referred to as its "global" config, and can be set by using either:
+
+- a config file, or
+- environment variables, or
+- CLI parameters
+
 By default Renovate checks if a file named `config.js` is present.
-Any other (`*.js`, `*.json`, `*.json5`, `*.yaml` or `*.yml`) file is supported, when you reference it with the `RENOVATE_CONFIG_FILE` environment variable (e.g. `RENOVATE_CONFIG_FILE=config.yaml`).
+Any other (`*.js`, `*.json`, `*.json5`, `*.yaml` or `*.yml`) file is supported, when you reference it with the `RENOVATE_CONFIG_FILE` environment variable (for example: `RENOVATE_CONFIG_FILE=config.yaml`).
 
 Some config is global-only, meaning that either it is only applicable to the bot administrator or it can only be controlled by the administrator and not repository users.
 Those are documented in [Self-hosted Configuration](../self-hosted-configuration.md).
 Your bot's global config can include both global as well as non-global configuration options, while user/repo config can only include non-global options.
-It is recommended to keep as much of the non-global config as possible in repo config files in order to provide maximum transparency to end users.
+We recommend that you keep as much of the non-global config as possible in repository config files.
+This way the Renovate end users can see as much of the bot's configuration as possible.
 
-If you are configuring using environment variables, there are two possibilities:
+If you are configuring Renovate using environment variables, there are two possibilities:
 
 - Upper-cased, camel-cased, `RENOVATE_`-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com`
-- Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, e.g. `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'`
+- Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, for example: `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'`
 
 If you combine both of the above then any single config option in the environment variable will override what's in `RENOVATE_CONFIG`.
 
 <!-- prettier-ignore -->
 !!! note
-    It's also possible to change the default prefix from `RENOVATE_` using `ENV_PREFIX`. e.g. `ENV_PREFIX=RNV_ RNV_TOKEN=abc123 renovate`.
+    It's also possible to change the default prefix from `RENOVATE_` using `ENV_PREFIX`.
+    For example: `ENV_PREFIX=RNV_ RNV_TOKEN=abc123 renovate`.
 
 #### Using `config.js`
 
@@ -145,13 +178,13 @@ module.exports = {
 
 `config.js` may also export a `Promise` of such an object, or a function that will return either a plain JavaScript object or a `Promise` of such an object.
 This allows one to include the results of asynchronous operations in the exported value.
-An example of a `config.js` that exports an async function (which is a function that returns a `Promise`) can be seen in a comment for [#10011: Allow autodiscover filtering for repo topic](https://github.com/renovatebot/renovate/issues/10011#issuecomment-992568583) and more examples can be seen in [`file.spec.ts`](https://github.com/renovatebot/renovate/blob/main/lib/workers/global/config/parse/file.spec.ts).
+An example of a `config.js` that exports an `async` function (which is a function that returns a `Promise`) can be seen in a comment for [#10011: Allow autodiscover filtering for repo topic](https://github.com/renovatebot/renovate/issues/10011#issuecomment-992568583) and more examples can be seen in [`file.spec.ts`](https://github.com/renovatebot/renovate/blob/main/lib/workers/global/config/parse/file.spec.ts).
 
 ### Authentication
 
 Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token.
 We recommend you use `@renovate-bot` as username if you're on a self-hosted server where you can set all usernames.
-We also recommend you configure `config.gitAuthor` with the same identity as your Renovate user, e.g. like `"gitAuthor": "Renovate Bot <renovate@whitesourcesoftware.com>"`.
+We also recommend you configure `config.gitAuthor` with the same identity as your Renovate user, for example: `"gitAuthor": "Renovate Bot <renovate@some.domain.test>"`.
 
 <!-- prettier-ignore -->
 !!! warning
@@ -171,16 +204,16 @@ Read the platform-specific docs to learn how to setup authentication on your pla
 
 ### GitHub.com token for release notes
 
-If you are running on any platform except github.com, it's important to also configure the environment variable `GITHUB_COM_TOKEN` containing a Personal Access Token for github.com.
-This account can actually be _any_ account on GitHub, and needs only read-only access.
+If you are running on any platform except github.com, you should also set the environment variable `GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it.
+This account can be _any_ account on GitHub, and needs only `read-only` access.
 It's used when fetching release notes for repositories in order to increase the hourly API limit.
 It's also OK to configure the same as a host rule instead, if you prefer that.
 
 <!-- prettier-ignore -->
 !!! note
-    If you're using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub) it is highly recommended to add a token.
-    Otherwise you will exceed the rate limit from the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies.
+    If you're using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic).
+    Otherwise you will exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies.
 
 ### Self-hosting examples
 
-For more examples on running Renovate self-hosted, please read our [Self-hosted examples](../examples/self-hosting.md) page.
+For more examples on running Renovate self-hosted, read our [Self-hosted examples](../examples/self-hosting.md) page.