@cryptotaxi247 / netdata-1 / commits / 532450d16

Installation + docker, improvements (#19987)

* Installation + docker, improvements * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Update packaging/docker/README.md Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud> * Address review comments --------- Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>

kanelatechnical committed Mar 28, 2025 at 12:45 UTC 532450d1629e76f01cd280721f27729b18e7b951

5 files changed +91 -161

packaging/docker/README.md

+43 -75

@@ -5,22 +5,15 @@ import TabItem from '@theme/TabItem';

6 ## Limitations running the Agent in Docker

8 -We don’t officially support running our Docker images with the Docker CLI `--user` option or the Docker Compose

9 -`user:` parameter. Such usage will usually still work, but some features will not be available when run this

10 -way. Note that the Agent will drop privileges appropriately inside the container during startup, meaning that even

11 -when run without these options, almost nothing in the container will actually run with an effective UID of 0.

8 +We don’t officially support using Docker’s `--user` option or Docker Compose’s `user:` parameter with our images. While they may work, some features could be unavailable. The Agent drops privileges at startup, so most processes don’t run as UID 0 even without these options.

13 -Our POWER8+ Docker images don’t support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,

14 -and unfortunately, not something we can realistically work around.

10 +Additionally, our **POWER8+ Docker images** don’t support the **FreeIPMI collector** due to a technical limitation in FreeIPMI itself, which we can’t work around.

12 ## Create a new Netdata Agent container

18 -You can create a new Agent container using either `docker run` or `docker-compose`. After using any method, you can

19 -visit the Agent dashboard `http://NODE:19999`.

14 +You can create a new Agent container with `docker run` or `docker-compose`, then access the dashboard at `http://NODE:19999`.

21 -The Netdata container requires different privileges and mounts to provide functionality similar to that provided by

22 -Netdata installed on the host. Below you can find a list of Netdata components that need these privileges and mounts,

23 -along with their descriptions.

16 +The Netdata container requires specific **privileges** and **mounts** to provide full monitoring capabilities equivalent to a direct host installation. Below is a list of required components and their purposes.

18 <details open>

19 <summary>Privileges</summary>

@@ -57,8 +50,7 @@ along with their descriptions.

51 Both methods create a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files

52 _within the container_ at `/etc/netdata`.

60 -See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from

61 -your _host_ machine, see [host-editable configuration](#with-host-editable-configuration).

53 +See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from your _host_ machine, see [host-editable configuration](#with-host-editable-configuration).

55 <Tabs>

56 <TabItem value="docker_run" label="docker run">

@@ -262,18 +254,11 @@ volumes:

254

255 ### With SSL/TLS enabled HTTP Proxy

256

265 -For a permanent installation on a public server, you

266 -should [secure the Netdata instance](/docs/netdata-agent/securing-netdata-agents.md). This

267 -section contains an example of how to install Netdata with an SSL reverse proxy and basic authentication.

257 +Below is an example of installing Netdata with an **SSL reverse proxy** and **basic authentication** using Docker.

258

269 -You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and

270 -email address for [Let's Encrypt](https://letsencrypt.org/) before starting.

259 +#### Caddyfile Setup

260

272 -#### Caddyfile

273 -

274 -This file needs to be placed in `/opt` with name `Caddyfile`. Here you customize your domain, and you need to provide

275 -your email address to obtain a Let's Encrypt certificate. Certificate renewal will happen automatically and will be

276 -executed internally by the caddy server.

261 +Place the following `Caddyfile` in `/opt`, customizing the domain and adding your email for **Let’s Encrypt**. The certificate will renew automatically via the Caddy server.

262

263 ```caddyfile

264 netdata.example.org {

@@ -343,15 +328,11 @@ to Caddyfile.

328

329 ### With Docker socket proxy

330

346 -> **Note**: Using Netdata with a Docker socket proxy might have some features not working as expected. It hasn't been fully tested by the Netdata team.

331 +> **Note:** Using Netdata with a Docker socket proxy may cause some features to not work as expected. It hasn't been fully tested by the Netdata team.

332

348 -Deploy a Docker socket proxy that accepts and filters out requests using something like

349 -[HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md) or

350 -[CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to

351 -the `/containers` endpoint.

333 +For better security, deploy a **Docker socket proxy** with a tool like [HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md) or [CetusGuard](https://github.com/hectorm/cetusguard). This ensures the socket is **read-only** and restricted to the `/containers` endpoint.

334

353 -The reason it's safer to expose the socket to the proxy is because Netdata has a TCP port exposed outside the Docker

354 -network. Access to the proxy container is limited to only within the network.

335 +Exposing the socket to a proxy is safer because Netdata’s TCP port is accessible outside the Docker network, while the proxy container remains isolated within it.

336

337 #### HAProxy

338

@@ -457,9 +438,8 @@ other services that require access.

438

439 Netdata can be run successfully in a non-root environment, such as [rootless Docker](https://docs.docker.com/engine/security/rootless/).

440

460 -However, it should be noted that Netdata's data collection capabilities are considerably restricted in rootless Docker

461 -due to its inherent limitations. While Netdata can function in a rootless environment, it can’t access certain

462 -resources that require elevated privileges. The following components don’t work:

441 +Netdata can run in a rootless Docker environment, but its data collection is limited due to restricted access to resources requiring elevated privileges.

442 +The following components won't work:

443

444 - container network interfaces monitoring (cgroup-network helper)

445 - disk I/O and file descriptors of applications and processes (apps.plugin)

@@ -471,8 +451,7 @@ resources that require elevated privileges. The following components don’t wor

451

452 This method creates a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files

453 _within the container_ at `/etc/netdata`.

474 -See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from

475 -your _host_ machine, see [host-editable configuration](#with-host-editable-configuration).

454 +See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from your _host_ machine, see [host-editable configuration](#with-host-editable-configuration).

455

456 <Tabs>

457 <TabItem value="docker_run" label="docker run">

@@ -523,14 +502,11 @@ The official `netdata/netdata` Docker image provides the following named tags:

502 | `vX.Y` | the major and minor version (for example, `v1.40`). |

503 | `vX` | just the major version (for example, `v1`). |

504

526 -The tags for minor and major versions are updated whenever a release that matches this tag is published (for example,

527 -if `v1.40.1` were to be published, the `v1.40` tag would be updated to it instead of pointing to `v1.40.0`).

505 +Minor and major version tags update with each matching release. For example, if `v1.40.1` is published, the `v1.40` tag moves from `v1.40.0` to `v1.40.1`.

506

529 -## Configure Agent containers

507 +## Configure Agent Containers

508

531 -If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), and you

532 -want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata`

533 -with the name of your container.

509 +If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container) and need to edit its configuration, first attach to the container with `docker exec`, replacing `netdata` with your container’s name.

510

511 ```bash

512 docker exec -it netdata bash

@@ -538,15 +514,13 @@ cd /etc/netdata

514 ./edit-config netdata.conf

515 ```

516

541 -You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command

542 -to restart the container: `docker restart netdata`.

517 +Restart the Agent to apply changes: exit the container if necessary, then run `docker restart netdata`.

518

519 ### Change the default hostname

520

546 -You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata

547 -Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it,

548 -you can safely stop and remove it. Your configuration and metrics data reside in persistent volumes and are reattached

549 -to the recreated container.

521 +A container’s hostname appears in both the local dashboard and Netdata Cloud.

522 +

523 +To change it after creation, stop and remove the container—it’s safe! Your configuration and metrics stay intact in persistent volumes and will reattach when you recreate the container.

524

525 If you use `docker-run`, use the `--hostname` option with `docker run`.

526

@@ -567,45 +541,39 @@ services:

541 hostname: my_docker_compose_netdata

542 ```

543

570 -If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the

571 -above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on

572 -how you created the container.

544 +If you prefer not to recreate the container, edit the Agent’s `netdata.conf` file. See [configuring Agent containers](#configure-agent-containers) for the right method based on how you created it.

545

574 -Alternatively, you can directly use the hostname from the node running the container by mounting `/etc/hostname` from

575 -the host in the container. With `docker run`, this can be done by adding `--volume /etc/hostname:/host/etc/hostname:ro` to

576 -the options. If you’re using Docker Compose, you can add an entry to the container's `volumes` section

577 -reading `- /etc/hostname:/host/etc/hostname:ro`.

546 +Alternatively, use the **host’s hostname** by mounting `/etc/hostname` in the container:

547

579 -## Adding extra packages at runtime

548 +- **With `docker run`**, add:

549 + ```sh

550 + --volume /etc/hostname:/host/etc/hostname:ro

551 + ```

552 +- **With Docker Compose**, add this to the `volumes` section:

553 + ```yaml

554 + - /etc/hostname:/host/etc/hostname:ro

555 + ```

556

581 -By default, the official Netdata container images don’t include a number of optional runtime dependencies. You

582 -can add these dependencies, or any other APT packages, at runtime by listing them in the environment variable

583 -`NETDATA_EXTRA_DEB_PACKAGES`.

557 +## Adding extra packages at runtime

558

585 -Commonly useful packages include:

559 +By default, Netdata’s official container images exclude some optional runtime dependencies. You can install them at runtime by setting the `NETDATA_EXTRA_DEB_PACKAGES` environment variable.

560

587 -- `apcupsd`: For monitoring APC UPS devices.

588 -- `lm-sensors`: For monitoring hardware sensors.

589 -- `netcat-openbsd`: For IRC alert support.

561 +Commonly useful packages:

562 +- `apcupsd` – Monitors APC UPS devices.

563 +- `lm-sensors` – Monitors hardware sensors.

564 +- `netcat-openbsd` – Enables IRC alerts.

565

566 ## Health Checks

567

593 -Our Docker image provides integrated support for health checks through the standard Docker interfaces.

594 -

595 -You can control how the health checks run by using the environment variable `NETDATA_HEALTHCHECK_TARGET` as follows:

568 +Netdata’s Docker image supports **health checks** via standard Docker interfaces. You can control them using the `NETDATA_HEALTHCHECK_TARGET` environment variable:

569

597 -- If left unset, the health check will attempt to access the `/api/v1/info` endpoint of the Agent.

598 -- If set to the exact value 'cli', the health check script will use `netdatacli ping` to determine if the Agent is

599 - running correctly or not. This is sufficient to ensure that Netdata didn’t hang during startup, but doesn’t provide

600 - a rigorous verification that the daemon is collecting data or is otherwise usable.

601 -- If set to anything else, the health check will treat the value as a URL to check for a 200 status code on. In most

602 - cases, this should start with `http://localhost:19999/` to check the Agent running in the container.

570 +- **Unset** – Defaults to checking `/api/v1/info`.

571 +- **`cli`** – Uses `netdatacli ping` to confirm the Agent is running (but not full data collection).

572

604 -In most cases, the default behavior of checking the `/api/v1/info` endpoint will be enough. If you’re using a

605 -configuration which disables the web server or restricts access to certain APIs, you will need to use a non-default

606 -configuration for health checks to work.

573 +The default `/api/v1/info` check is usually sufficient. However, if the web server is disabled or API access is restricted, you'll need to customize the health check configuration.

574

575 ## Publish a test image to your own repository

576

577 At Netdata, we provide multiple ways of testing your Docker images using your own repositories.

611 -You may either use the command line tools available or take advantage of our GitHub Actions infrastructure.

578 +

579 +You may either use the command line tools available or take advantage of our GitHub Actions infrastructure.

\ No newline at end of file

packaging/installer/methods/macos.md

+4 -4

@@ -1,9 +1,5 @@

1 # Install Netdata on macOS

3 -Netdata works on macOS, albeit with some limitations.

4 -The number of charts displaying system metrics is limited, but you can use any of Netdata's [external plugins](/src/plugins.d/README.md) to monitor any services you might have installed on your macOS system.

5 -You could also use a macOS system as the parent node in a [streaming configuration](/src/streaming/README.md).

6 -

3 You can install Netdata in one of the three following ways:

5 - **[Install Netdata with the our automatic one-line installation script (recommended)](#install-netdata-with-our-automatic-one-line-installation-script)**,

@@ -109,3 +105,7 @@ We don't recommend installing Netdata from source on macOS, as it can be difficu

105 > Your Netdata configuration directory will be at `/usr/local/netdata/`.

106 > Your stock configuration directory will be at `/usr/local/lib/netdata/conf.d/`.

107 > The installer will also install a startup plist to start Netdata when your macOS system boots.

108 +

109 +Netdata works on macOS, albeit with some limitations.

110 +The number of charts displaying system metrics is limited, but you can use any of Netdata's [external plugins](/src/plugins.d/README.md) to monitor any services you might have installed on your macOS system.

111 +You could also use a macOS system as the parent node in a [streaming configuration](/src/streaming/README.md).

\ No newline at end of file

packaging/installer/methods/no_ipv4.md

+4 -6

@@ -1,13 +1,11 @@

1 # Installing on hosts without IPv4 connectivity

3 -Our regular installation process requires access to a number of GitHub services that do not have IPv6 connectivity.

5 -As such, using the kickstart install script on such hosts generally does not work, and will typically fail with an error from cURL or wget about connection timeouts.

6 -

7 -You can check if your system is affected by this by attempting to connect to (or ping) `https://api.github.com/`. Failing to connect indicates that this issue affects you.

4 +Our regular installation process requires access to GitHub services that lack IPv6 connectivity. Using the kickstart install script on such hosts may result in connection timeouts from cURL or wget.

6 +To check if your system is affected, try connecting to or pinging `https://api.github.com/`. If it fails, the issue impacts you.

7 There are three potential workarounds for this:

11 -1. You can configure your system with a proper IPv6 transition mechanism, such as NAT64. GitHub’s anachronisms affect many projects other than just Netdata. There are, unfortunately, a number of other services out there that do not provide IPv6 connectivity, so taking this route is likely to save you time in the future as well.

9 +1. You can configure your system with an IPv6 transition mechanism like NAT64. GitHub’s lack of IPv6 affects many projects, not just Netdata, and other services may have similar issues. Setting this up can save you time in the future.

10 2. If you are using a system that we publish native packages for (see our [platform support policy](/docs/netdata-agent/versions-and-platforms.md) for more details), you can manually set up our native package repositories as outlined in our [native package install documentation](/packaging/installer/methods/packages.md). Our official package repositories do provide service over IPv6, so they work without issue on hosts without IPv4 connectivity.

13 -3. If neither of the above options work for you, you can still install using our [offline installation instructions](/packaging/installer/methods/offline.md), though do note that the offline install source must be prepared from a system with IPv4 connectivity.

11 +3. If neither of the above options work for you, you can still install using our [offline installation instructions](/packaging/installer/methods/offline.md), though do note that the offline install source must be prepared from a system with IPv4 connectivity.

\ No newline at end of file

packaging/installer/methods/offline.md

+4 -14

@@ -1,18 +1,11 @@

1 # Install Netdata on offline systems

3 -Our kickstart install script provides support for installing the Netdata Agent on air-gapped systems which do not have a

4 -usable internet connection by prefetching all of the required files so that they can be copied to the target system.

5 -Currently, we only support using static installs with this method. There are tentative plans to support building

6 -locally on offline systems as well, but there is currently no estimate of when this functionality may be implemented.

8 -Users who wish to use native packages on offline systems may be able to do so using whatever tooling their

9 -distribution already provides for offline package management (such as `apt-offline` on Debian or Ubuntu systems),

10 -but this is not officially supported.

4 +Our kickstart script enables offline Netdata Agent installation by prefetching required files (static installs only for now). Future support for local builds is possible, but no ETA. For offline systems, users can try their distro’s package tools (e.g., `apt-offline`), though it's not officially supported.

6 ## Preparing the offline installation source

14 -The first step to installing Netdata on an offline system is to prepare the offline installation source. This can

15 -be as a regular user from any internet connected system that has the following tools available:

8 +The first step in installing Netdata on an offline system is preparing the offline installation source. This can be done as a regular user on any internet-connected system with the following tools available:

10 - cURL or wget

11 - sha256sum or shasum

@@ -39,10 +32,7 @@ appropriate option for the kickstart script.

33 ## Installing on the target system

42 -Once you have prepared the offline install source, you need to copy the offline install source directory to the

43 -target system. This can be done in any manner you like, as long as filenames are not changed.

35 +Once you have prepared the offline install source, you need to copy the offline install source directory to the target system. This can be done in any manner you like, as long as filenames are not changed.

37 After copying the files, simply run the `install.sh` script located in the

46 -offline install source directory. It accepts all the [same options as the kickstart script](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) for further

47 -customization of the installation, though it will default to not enabling automatic updates (as they are not

48 -supported on offline installs).

38 +offline install source directory. It accepts all the [same options as the kickstart script](/packaging/installer/methods/kickstart.md#optional-parameters-to-alter-your-installation) for further customization of the installation, though it will default to not enabling automatic updates (as they are not supported on offline installs).

\ No newline at end of file

packaging/installer/methods/packages.md

+36 -62

@@ -1,20 +1,12 @@

1 # Install Netdata using native DEB/RPM packages

3 -For most common Linux distributions that use either DEB or RPM packages, Netdata provides pre-built native packages

4 -for current releases in-line with

5 -our [official platform support policy](/docs/netdata-agent/versions-and-platforms.md).

6 -These packages will be used by default when attempting to install on a supported platform using our

7 -[kickstart.sh installer script](/packaging/installer/methods/kickstart.md).

3 +For most DEB- or RPM-based Linux distributions, Netdata provides pre-built native packages, following our [platform support policy](/docs/netdata-agent/versions-and-platforms.md).

9 -When using the kickstart script, you can force usage of native DEB or RPM packages by passing the option

10 -`--native-only` when invoking the script. This will cause it to only attempt to use native packages for the install,

11 -and fail if it cannot do so.

5 +Our [kickstart.sh installer](/packaging/installer/methods/kickstart.md) uses these by default on supported platforms. To force native DEB or RPM packages, add `--native-only` when running the script—it will fail if native packages aren’t available.

7 > **Note**

14 ->

15 -> In July 2022, we switched hosting of our native packages from Package Cloud to self-hosted repositories.

16 -> Until late 2024 we continued to provide packages via Package Cloud, but we have since then switched to only

17 -> providing packages via our repositories.

8 +>

9 +> Until late 2024 we continued to provide packages via Package Cloud, but we have since then switched to only providing packages via our repositories.

11 ## Manual setup of RPM packages

@@ -35,33 +27,28 @@ Within each top level group of repositories, there are directories for each supp

27 - `ol`: Is for Oracle Linux and binary compatible distros.

28 - `opensuse`: Is for openSUSE and binary compatible distros.

38 -Under each of those directories is a directory for each supported release of that distribution, and under that a

39 -directory for each supported CPU architecture which contains the actual repository.

30 +Each distribution has a directory for supported releases, with subdirectories for each CPU architecture containing the actual repository.

41 -For example, for stable release packages for RHEL 9 on 64-bit x86, the full URL for the repository would be

42 -<https://repository.netdata.cloud/repos/stable/el/9/x86_64/>

32 +For example, the stable release for RHEL 9 on 64-bit x86 is at:

33 +<https://repository.netdata.cloud/repos/stable/el/9/x86_64/>

44 -Our RPM packages and repository metadata are signed using a GPG key with a user name of ‘Netdatabot’. The

45 -current key fingerprint is `6E155DC153906B73765A74A99DD4A74CECFA8F4F`. The associated public key can be fetched from

46 -`https://repository.netdata.cloud/netdatabot.gpg.key`.

35 +Our RPM packages and repository metadata are signed with a GPG key (`Netdatabot`), fingerprint:

36 +`6E155DC153906B73765A74A99DD4A74CECFA8F4F`.

37 +Public key:

38 +<https://repository.netdata.cloud/netdatabot.gpg.key>

48 -If you are explicitly configuring a system to use our repositories, the recommended setup is to download the

49 -appropriate repository configuration package from <https://repository.netdata.cloud/repos/repoconfig/index.html>

50 -and install it directly on the target system using the system package manager. This will ensure any packages

51 -needed to use the repository are also installed, and will help enable a seamless transition if we ever need to

52 -change our infrastructure.

40 +For manual repository setup, download the appropriate config package from:

41 +<https://repository.netdata.cloud/repos/repoconfig/index.html>

42 +Install it with your package manager to ensure dependencies and smooth updates.

54 -> **Note**

55 ->

56 -> On RHEL and other systems that use the `el` repositories, some of the dependencies for Netdata can only be found

57 -> in the EPEL repository, which is not enabled or installed by default on most of these systems. This additional

58 -> repository _should_ be pulled in automatically by our repository config packages, but if it is not you may need

59 -> to manually install `epel-release` to be able to successfully install the Netdata packages.

44 +> **Note:**

45 +> On RHEL and other `el`-based systems, some Netdata dependencies are in the EPEL repository, which isn’t enabled by default.

46 +> Our config packages should handle this, but if not, install `epel-release` manually.

48 ## Manual setup of DEB packages

63 -Netdata’s official DEB repositories are hosted at <https://repository.netdata.cloud/repos/index.html>. We provide four groups of

64 -repositories at that top level:

50 +Netdata’s official DEB repositories are hosted at <https://repository.netdata.cloud/repos/index.html>.

51 +We provide four groups of repositories at that top level:

53 - `stable`: Contains packages for stable releases of the Netdata Agent.

54 - `edge`: Contains packages for nightly builds of the Netdata Agent.

@@ -73,12 +60,10 @@ Within each top level group of repositories, there are directories for each supp

60 - `debian`: Is for Debian Linux and binary compatible distros.

61 - `ubuntu`: Is for Ubuntu Linux and binary compatible distros.

76 -Under each of these directories is a directory for each supported release, corresponding to the release codename.

63 +Each directory contains subdirectories for supported releases, named by codename.

78 -These repositories are set up as what Debian calls ‘flat repositories’, and are available via both HTTP and HTTPS.

79 -Additionally, our repositories support acquiring repository metadata by-hash, which leads to use of URLs similar to

80 -`http://repository.netdata.cloud/repos/edge/ubuntu/focal/by-hash/SHA256/91ccff6523a3c4483ebb539ff2b4adcd3b6b5d0c0c2c9573c5a6947a127819bc`,

81 -and this is the preferred method for updating metadata as it is more reliable.

65 +Our repositories use **flat repository** structure (per Debian standards) and are accessible via HTTP and HTTPS. They also support metadata retrieval **by-hash**, which improves reliability. Example:

66 +`http://repository.netdata.cloud/repos/edge/ubuntu/focal/by-hash/SHA256/91ccff6523a3c4483ebb539ff2b4adcd3b6b5d0c0c2c9573c5a6947a127819bc`

68 As a result of this structure, the required APT sources.list entry for stable packages for Debian 11 (Bullseye) is:

@@ -102,10 +87,10 @@ Our DEB packages and repository metadata are signed using a GPG key with a user

87 current key fingerprint is `6E155DC153906B73765A74A99DD4A74CECFA8F4F`. The associated public key can be fetched from

88 `https://repository.netdata.cloud/netdatabot.gpg.key`.

105 -If you are explicitly configuring a system to use our repositories, the recommended setup is to download the

106 -appropriate repository configuration package from <https://repository.netdata.cloud/repos/repoconfig/index.html> and install it

107 -directly on the target system using the system package manager. This will ensure any packages needed to use the

108 -repository are also installed, and will help enable a seamless transition if we ever need to change our infrastructure.

90 +For manual repository setup, download the appropriate config package from:

91 +<https://repository.netdata.cloud/repos/repoconfig/index.html>

92 +

93 +Install it using your package manager to ensure all dependencies are met and to allow a smooth transition if our infrastructure changes.

95 ## Local mirrors of the official Netdata repositories

@@ -117,29 +102,18 @@ Local mirrors of our official repositories can be created in one of two ways:

102 2. Using a regular website mirroring tool, such as GNU wget’s `--mirror` option. For this approach, simply point

103 your mirroring tool at `https://repository.netdata.cloud/repos/`, and everything should just work.

104

120 -We do not provide official support for mirroring our repositories, but we do have some tips for anyone looking to do so:

121 -

122 -- Excluding special cases of caching proxies (such as apt-cacher-ng), our repository configuration packages _DO NOT_

123 - work with custom local mirrors. Thus, you will need to manually configure your systems to use your local mirror.

124 -- Packages are published as they are built, with 64-bit x86 packages being built first, followed by 32-bit x86,

125 - and then non-x86 packages in alphabetical order of the CPU architecture. Because of the number of different

126 - packages being built, this means that packages for a given nightly build or stable release are typically published

127 - over the course of a few hours, usually starting about 15-20 minutes after the build or release is started.

128 -- Repository metadata may be updated as frequently as six times an hour, depending on whether or not there are

129 - new packages for a given repository. However, it is generally not worth it to attempt to

130 - synchronize a mirror of our repositories more frequently than once an hour.

131 -- A full mirror of all of our repositories currently requires up to 100 GB of storage space, though the exact

132 - amount of space needed fluctuates over time. Because of this, users seeking to mirror our repositories are

133 - encouraged to mirror only those repositories they actually need instead of mirroring everything.

134 -- If syncing daily (or less frequently), some time between 05:00 and 08:00 UTC each day is usually the safest

135 - time to do so, as publishing nightly packages will almost always be done by this point, and publishing of stable

136 - releases typically happens after that time window.

137 -- If you intend to use our existing GPG signatures on the repository metadata and packages, you probably also want

138 - a local copy of our public GPG key, which can be fetched from `https://repository.netdata.cloud/netdatabot.gpg.key`.

105 +We don’t officially support mirroring our repositories, but here are some tips:

106 +

107 +- Our repository config packages **don’t** work with custom mirrors (except caching proxies like `apt-cacher-ng`), so you’ll need to configure mirrors manually.

108 +- Packages are built and published in stages: 64-bit x86 first, then 32-bit x86, followed by other architectures in alphabetical order. Publishing takes a few hours.

109 +- Repository metadata updates up to six times an hour, but syncing more than once per hour isn’t necessary.

110 +- A full mirror requires up to **100 GB** of storage, so mirror only what you need.

111 +- For daily syncing, **05:00–08:00 UTC** is ideal, as nightly packages are usually published by then.

112 +- If using our GPG signatures, grab our public key:

113 + <https://repository.netdata.cloud/netdatabot.gpg.key>

114

115 ## Public mirrors of the official Netdata repositories

116

117 There are no official public mirrors of our repositories.

118

144 -If you wish to provide a public mirror of our official repositories, you are free to do so, but we kindly ask that

145 -you make it clear to your users that your mirror is not an official mirror of our repositories.

119 +If you wish to provide a public mirror of our official repositories, you are free to do so, but we kindly ask that you make it clear to your users that your mirror is not an official mirror of our repositories.

\ No newline at end of file