diff --git a/docs/usage/getting-started/running.md b/docs/usage/getting-started/running.md index d513a880349f9e62811476e6eb26ba1bdb1aff28..3554dff73ec11c20a6818fd90ab46b4dc7c1af93 100644 --- a/docs/usage/getting-started/running.md +++ b/docs/usage/getting-started/running.md @@ -35,39 +35,37 @@ The `renovate` npm package is compatible with all of Renovate's supported platfo 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. +Both `linux/amd64` and `linux/arm64` architectures are supported, but you may still find some bugs in the `arm64` image. 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: +There are two Docker image flavors: -- The `-slim` image -- The default "full" image, this is the image you'll get if you use the `latest` tag +- The default image, which installs required tools at runtime (default for `latest` tag), +- The `-full` image, which comes with latest or very recent versions of every tool pre-installed -##### The slim image +##### The default image (formerly `slim`) -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. +The default image only comes with the Node.js environment. +Renovate will then install any needed tools when it runs. +Read the `binarySource=install` documentation for more details. +We recommend this default image for most users. + +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. 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 default image - -The default image comes with most package managers that Renovate supports, but not _all_ package managers. +##### The full image -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. +The `-full` image comes with most package managers that Renovate supports, but not _all_ package managers. 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: +The full image is for users who don't want to download or install things at runtime. +This image has some downsides, because it: - Comes pre-installed with _one_ version of each language/manager - usually the latest - Weighs several gigabytes diff --git a/docs/usage/self-hosted-configuration.md b/docs/usage/self-hosted-configuration.md index f090e9fcf3dbf4dc9d920bad66450509237a499e..a1a844a1331800d4564c9aff0c6ac0b723ee0069 100644 --- a/docs/usage/self-hosted-configuration.md +++ b/docs/usage/self-hosted-configuration.md @@ -152,19 +152,22 @@ If the "development branch" is configured but the branch itself does not exist ( ## binarySource Renovate often needs to use third-party tools in its PRs, like `npm` to update `package-lock.json` or `go` to update `go.sum`. -By default, Renovate uses a child process to run such tools, so they must be: -- installed before running Renovate -- available in the path +Renovate supports four possible ways to access those tools: -But you can tell Renovate to use "sidecar" containers for third-party tools by setting `binarySource=docker`. -For this to work, `docker` needs to be installed and the Docker socket available to Renovate. -Now Renovate uses `docker run` to create containers like Node.js or Python to run tools in as-needed. +- `global`: Uses pre-installed tools, e.g. `npm` installed via `npm install -g npm`. +- `install` (default): Downloads and installs tools at runtime if running in a [Containerbase](https://github.com/containerbase/base) environment, otherwise falls back to `global` +- `docker`: Runs tools inside Docker "sidecar" containers using `docker run`. +- `hermit`: Uses the [Hermit](https://github.com/cashapp/hermit) tool installation approach. + +Starting in v36, Renovate's default Docker image (previously referred to as the "slim" image) uses `binarySource=install` while the "full" Docker image uses `binarySource=global`. +If you are running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image. -Additionally, when Renovate is run inside a container built using [`containerbase`](https://github.com/containerbase), such as the official Renovate images on Docker Hub, then `binarySource=install` can be used. -This mode means that Renovate will dynamically install the desired version of each tool needed. +If you are building your own Renovate image, e.g. by installing Renovate using `npm`, then you will need to ensure that all necessary tools are installed globally before running Renovate so that `binarySource=global` will work. -If all projects are managed by Hermit, you can tell Renovate to use the tool versions specified in each project via Hermit by setting `binarySource=hermit`. +The `binarySource=docker` approach should not be necessary in most cases now and `binarySource=install` is recommended instead. +If you have a use case where you cannot use `binarySource=install` but can use `binarySource=docker` then please share it in a GitHub Discussion so that the maintainers can understand it. +For this to work, `docker` needs to be installed and the Docker socket available to Renovate. ## cacheDir diff --git a/readme.md b/readme.md index 3bc4254ab07a865a367966369958776d2957045d..6afc374ab33f34c6c37d1361e11185bdf5782a1d 100644 --- a/readme.md +++ b/readme.md @@ -110,8 +110,8 @@ To get help with your configuration, go to the [discussions tab in the Renovate To run your own instance of Renovate you have several options: - Install the `renovate` CLI tool from npmjs, run it on a schedule (e.g. using `cron`) -- Run the `renovate/renovate` Docker Hub image (same content/versions as the CLI tool), run it on a schedule -- Run the `renovate/renovate:slim` Docker Hub image if you only use package managers that don't need third-party binaries (e.g. JavaScript, Docker, NuGet, pip) +- Run the `renovate/renovate:full` Docker Hub image (same content/versions as the CLI tool), run it on a schedule +- Run the `renovate/renovate:latest` Docker Hub image if you only use package managers that don't need third-party binaries (e.g. JavaScript, Docker, NuGet, pip) [More details on the self-hosting development](https://github.com/renovatebot/renovate/blob/main/docs/usage/getting-started/running.md).