diff --git a/documentation/Makefile b/documentation/Makefile index e12dc8090a..e86de90872 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -14,20 +14,36 @@ doc-check-images: ## Check if all images are used in documentation doc-remove-images: ## Remove unused images from documentation @ACTION=remove $(DIR)/resources/bin/check-images.sh -doc-build: ## Build documentation +doc-build: ## Build documentation (used in CI) # This command is used to build and deploy a preview to onrender.com # Preview URL: https://pmm-doc.onrender.com mkdocs build -f $(DIR)/mkdocs.yml -doc-build-pdf: ## Build documentation in PDF format +doc-build-pdf: ## Build documentation in PDF format + docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build perconalab/pmm-doc-md:latest \ + bash -c " \ + cp -r /docs/* /build/ && \ + git init && \ + git config user.email 'doc-team@percona.com' && \ + git add --all && \ + git commit -am 'Initial commit' > /dev/null && \ + mkdocs build -f mkdocs-pdf.yml && \ + cp /build/site/pdf/*.pdf /docs/ \ + " + +doc-build-image: ## Build perconalab/pmm-doc-md:latest image # @docker buildx build --platform=linux/amd64 --progress=plain -t perconalab/pmm-doc-md:latest -f documentation/resources/Dockerfile.build . - docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md:latest \ - bash -c "cp -r /docs/* /build/ && \ - ls -la /build && \ - git init && \ - git config user.email 'doc-team@percona.com' && \ - git add --all && \ - git commit -am 'Initial commit' && \ - mkdocs build -f mkdocs-pdf.yml && \ - cp /build/site/pdf/*.pdf /docs/" + +doc-build-preview: ## Build documentation and preview at http://localhost:8000 + docker run --rm --platform=linux/amd64 -p 8000:8000 -v $(DIR):/docs -w /build perconalab/pmm-doc-md:latest \ + bash -c " \ + cp -r /docs/* /build/ && \ + git init && \ + git config user.email 'doc-team@percona.com' && \ + git add --all && \ + git commit -am 'Initial commit' > /dev/null && \ + mkdocs serve -f mkdocs.yml --dev-addr=0.0.0.0:8000 \ + " +doc-search-icons: ## Search for icons that can be used in documentation + @open https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search diff --git a/documentation/WRITERS-NOTES.md b/documentation/WRITERS-NOTES.md index e64fe7f2f9..11f2cc0846 100644 --- a/documentation/WRITERS-NOTES.md +++ b/documentation/WRITERS-NOTES.md @@ -125,8 +125,19 @@ In some places, we have used variables themselves to solve the problem. In other ## Icons +Currently, we use three different sets of icons: + +- Native Mkdocs Material icons and emojis +- Iconscount Unicons +- FontAwesome Icons + +The preference should be given to Mkdocs Material icons, since they were initially designed for `mkdocs` project and work very well with it. In rare cases, when an icon cannot be found in Mkdocs Material, you can find a suitable one on Iconscout. FontAwesome icons do not play well with Mkdocs, so use them with caution and don't forget to apply additional CSS styles in case they don't render well in PDF. + +Ideally, we should migrate to using just the two first sets. + Use HTML for icons: +- For Material Theme Icons (`:` prefix and suffix), go to , find an icon, select it and copy the code here. - For PMM UI (Grafana) icons (`uil-` prefix), go to , find an icon, select 'Font' and copy the code here. - For Font Awesome (`fa-` prefix), go to , find an icon, copy the code. diff --git a/documentation/docs/css/extra.css b/documentation/docs/css/extra.css index 892c792163..d1dc1c36bd 100644 --- a/documentation/docs/css/extra.css +++ b/documentation/docs/css/extra.css @@ -1,8 +1,28 @@ @media print { - /* Adjusts positioning of admonition icon */ - .md-typeset :is(.admonition-title,summary):before { - top: 0.6rem; - left: 0.6rem; - } + /* Adjusts positioning of admonition icon */ + .md-typeset :is(.admonition-title,summary):before { + top: 0.6rem; + left: 0.6rem; } + + /* Do not render html tags with this class in PDF */ + .no-pdf { + display: none !important; + } + + /* Modify rendering of numbered lists in PDF */ + .power-number+ol>li::before, + .power-number+ol ol>li::before { + background-color: var(--md-default-bg-color); + color: var(--md-typeset-color); + border-radius: 0; + width: 1.5em; + margin-left: -1.7em; + opacity: 1; + } + + .tabbed-content { + display: contents; + } +} \ No newline at end of file diff --git a/documentation/docs/index.md b/documentation/docs/index.md index a5a3ff1aed..0d0efb0613 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -1,6 +1,8 @@ # About PMM -:material-information: Info: This is the documentation for the latest release, **PMM {{release}}** Beta. See the [Release Notes](release-notes/3.0.0_Beta.md) for details. +!!! info "" + + This is the documentation for the latest release, **PMM {{release}}** Beta. See the [Release Notes](release-notes/3.0.0_Beta.md) for details. Percona Monitoring and Management (PMM) is an open source database observability, monitoring, and management tool for use with MySQL, PostgreSQL, MongoDB, and the servers on which they run. It enables you to view node- to single-query performance metrics for all of your databases in a single place. @@ -14,7 +16,7 @@ Percona Monitoring and Management (PMM) is an open source database observability Would you like to see a preview of our Home page? Take a look at our free, live [demo](https://pmmdemo.percona.com/). -
+
## :material-telescope: Discover { .title } @@ -33,7 +35,7 @@ Ready to dive into PMM? Follow our simple, step-by-step installation instruction
-## :fontawesome-solid-gear: Configure { .title } +## :material-cog: Configure { .title } Are you ready to begin configuring PMM but need help figuring out how to begin? Let's dive in together. @@ -49,6 +51,3 @@ Looking for reliable and easy-to-use resources to tackle your daily challenges w
- - - diff --git a/documentation/docs/install-pmm/index.md b/documentation/docs/install-pmm/index.md index dd6a2074dd..03e56a7e0b 100644 --- a/documentation/docs/install-pmm/index.md +++ b/documentation/docs/install-pmm/index.md @@ -15,13 +15,13 @@ Install and run at least one PMM Server. Choose from the following options: PMM Server is not currently available as a native ARM64 build. For ARM-based systems, consider using the Docker or Podman installation methods, which can run x86_64 images via emulation on ARM platforms. -| Use | **Benefits** | **Drawbacks**| +| Use | :material-thumb-up: **Benefits** | :material-thumb-down: **Drawbacks**| |---|---|--- | [Docker] | 1. Quick
2. Simple
3. Rootless | Additional network configuration required. -| [Podman] | 1. Quick
2. Simple
3. Rootless |Podman installation required. -| [Helm] (Technical Preview) | 1. Quick
2. Simple
3. Cloud
4. Rootless| Requires running Kubernetes cluster. +| [Podman] | 1. Quick
2. Simple
3. Rootless | Podman installation required. +| [Helm] (Technical Preview) | 1. Quick
2. Simple
3. Cloud-compatible
4. Rootless| Requires running a Kubernetes cluster. | [Virtual appliance] | 1. Easily import into Hypervisor of your choice
2. Rootless| More system resources compared to Docker footprint. -| [Amazon AWS] | 1. Wizard-driven install.
2. Rootless| Non-free solution (infrastructure costs). +| [Amazon AWS] | 1. Wizard-driven install.
2. Rootless| Paid, incurs infrastructure costs. ## Install PMM Client @@ -29,21 +29,26 @@ Install and run PMM Client on every node where there is a service you want to mo The installation choices are: - === "With Docker" +=== "With Docker" - [Docker installation](client/index.md#docker) simplifies deployment across different architectures and automatically selects the appropriate image for your architecture (x86_64 or ARM64).=p][\;] + - [Docker installation](client/index.md#docker) simplifies deployment across different architectures and automatically selects the appropriate image for your architecture (x86_64 or ARM64). - === "Native installation" +=== "With package manager" - [Linux package](client/index.md#package-manager). Use `apt`, `apt-get`, `dnf`, `yum`. The package manager automatically selects the correct version for your architecture. - - [Binary package](client/index.md#binary-packa): Download the appropriate `.tar.gz` file for your architecture (x86_64 or ARM64). +=== "With binary package" + + - [Binary package](client/index.md#binary-package): Download the appropriate `.tar.gz` file for your architecture (x86_64 or ARM64). + !!! hint alert "Tips" Both binary installation and Docker containers can be run without root permissions. When installing on ARM-based systems, ensure you're using ARM64-compatible versions. Performance may vary between architectures. ## Add services + On each PMM Client instance, configure the nodes and services you want to monitor. + ??? info "Which services you can monitor?" - [MySQL] (and variants: Percona Server for MySQL, Percona XtraDB Cluster, MariaDB); diff --git a/documentation/docs/install-pmm/install-pmm-server/baremetal/podman/index.md b/documentation/docs/install-pmm/install-pmm-server/baremetal/podman/index.md index e519f06198..b0b5468ba4 100644 --- a/documentation/docs/install-pmm/install-pmm-server/baremetal/podman/index.md +++ b/documentation/docs/install-pmm/install-pmm-server/baremetal/podman/index.md @@ -166,7 +166,8 @@ On the other hand, the manual method offers a simpler setup with complete contro 4. Go to `https://localhost:8443` to access the PMM user interface in a web browser. If you are accessing the host remotely, replace `localhost` with the IP or server name of the host. For information on manually upgrading, see [Upgrade PMM Server using Podman](../../../../pmm-upgrade/upgrade_podman.md). -======= + + ## Run as non-privileged user to start PMM ??? info "Summary" @@ -288,4 +289,4 @@ To run Podman as a non-privileged user: sleep 80 timeout 60 podman wait --condition=running pmm-server ``` -
\ No newline at end of file +
diff --git a/documentation/docs/install-pmm/plan-pmm-installation/network_and_firewall.md b/documentation/docs/install-pmm/plan-pmm-installation/network_and_firewall.md index 064ffa0ef7..bb8bdfbfa1 100644 --- a/documentation/docs/install-pmm/plan-pmm-installation/network_and_firewall.md +++ b/documentation/docs/install-pmm/plan-pmm-installation/network_and_firewall.md @@ -9,15 +9,15 @@ For PMM to work correctly, your system's firewall should allow TCP traffic on th Ports to expose: | PMM component | TCP port | Direction | Description -|---------------|---------------|---------------|----------------------------------------------------------------------------------------------------------------- +|---------------|---------------|---------------|------------------------------------------------------------------------------------------ | PMM Server | 80 | both | HTTP server, used for gRPC over HTTP and web interface (**insecure**, use with caution). | PMM Server | 443 | both | HTTPS server, used for gRPC over HTTPS and web interface (secure, use of SSL certificates is highly encouraged). Other ports: | PMM component | TCP port | Direction | Description -|---------------|---------------|---------------|--------------------------------------------------------------- -| PMM Server | 7771 | both | gRPC, used for communication between `pmm-agent`, `pmm-admin`. +|---------------|---------------|---------------|----------------------------------------------------------------- +| PMM Server | 7771 | both | gRPC, used for communication between `pmm-agent` and `pmm-admin`. | PMM Server | 7772 | out | HTTP1 server, used for older links like `logs.zip`. | PMM Server | 7773 | out | Debugging. | `pmm-agent` | 7777 | out | Default `pmm-agent` listen port. @@ -28,7 +28,7 @@ Other ports: Depending on your architecture other ports may also need to be exposed. - For `pmm-agent`, the default listen port is 7777. - - The default port range for `pmm-agent` is large by default to accommodate any architecture size but it can be modified using the `--ports-min` and `--ports-max` flags, or modifying the configuration file. In network constraint environments, the range can be reduced to a minimum by allocating at least one port per agent monitored. Learn more about available settings for `pmm-agent` in [Percona PMM-Agent documentation](https://docs.percona.com/percona-monitoring-and-management/details/commands/pmm-agent.html). + - The default port range for `pmm-agent` is large by default to accommodate any architecture size but it can be modified using the `--ports-min` and `--ports-max` flags, or by changing the configuration file. In network constraint environments, the range can be reduced to a minimum by allocating at least one port per agent monitored. Learn more about available settings for `pmm-agent` in [Percona PMM-Agent documentation](https://docs.percona.com/percona-monitoring-and-management/3/use/commands/pmm-agent.html). ## Network configuration for locked-down environments For computers in a locked-down corporate environment without direct access to the Internet, make sure to enable access to Percona Platform services following the instructions in the [Percona Platform documentation](https://docs.percona.com/percona-platform/network.html). \ No newline at end of file diff --git a/documentation/docs/use/qan/panels/overview.md b/documentation/docs/use/qan/panels/overview.md index 4c0b59147c..efe7b1f766 100644 --- a/documentation/docs/use/qan/panels/overview.md +++ b/documentation/docs/use/qan/panels/overview.md @@ -29,12 +29,12 @@ Delete the search text and press Enter to see the full list again. - The first column is the object’s identifier. For **Query**, it is the query’s [Fingerprint](../../../reference/glossary.md#fingerprint). - The second column is the **Main metric**, containing a reduced graphical representation of the metric over time, called a **sparkline**, and a horizontal meter, filled to reflect a percentage of the total value. -- Additional values are revealed as mouse-over tool-tips. +- Additional values are revealed as mouse-over tooltips. -## Tool-tips +## Tooltips -- For the **Query** dimension, hovering over the information icon reveals the query ID and its example. -- Hovering on a column header reveals an informative tool-tip for that column. +- For the **Query** dimension, hovering over the information icon :material-information: reveals the query ID and its example. +- Hovering on a column header reveals an informative tooltip for that column. - Hovering on the main metric sparkline highlights the data point and a tooltip shows the data value under the cursor. ![!image](../../../images/PMM_Query_Analytics_Main_Metric_Sparkline.jpg) @@ -68,4 +68,4 @@ Delete the search text and press Enter to see the full list again. ![!image](../../../images/PMM_Query_Analytics_Devices_Pagination.jpg) -- Queries are grouped into pages of 25, 50 or 100 items. \ No newline at end of file +- Queries are grouped into pages of 25, 50 or 100 items. diff --git a/documentation/mkdocs-base.yml b/documentation/mkdocs-base.yml index 5202d3721d..4e6275a191 100644 --- a/documentation/mkdocs-base.yml +++ b/documentation/mkdocs-base.yml @@ -57,11 +57,11 @@ theme: extra_css: - https://unicons.iconscout.com/release/v3.0.3/css/line.css - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css - - css/extra.css - css/nocopy.css - css/design.css - css/osano.css - css/pmm.css + - css/extra.css extra_javascript: - js/promptremover.js @@ -78,7 +78,7 @@ markdown_extensions: meta: {} md_in_html: {} smarty: - smart_angled_quotes: true + smart_angled_quotes: true pymdownx.details: {} pymdownx.mark: {} pymdownx.smartsymbols: {} diff --git a/documentation/mkdocs-pdf.yml b/documentation/mkdocs-pdf.yml index 91390f141d..0ae7e55926 100644 --- a/documentation/mkdocs-pdf.yml +++ b/documentation/mkdocs-pdf.yml @@ -1,5 +1,5 @@ # MkDocs configuration for PDF output -# Usage: ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml +# Usage: mkdocs build -f mkdocs-pdf.yml INHERIT: mkdocs-base.yml plugins: @@ -9,8 +9,7 @@ plugins: with-pdf: output_path: "pdf/PerconaMonitoringAndManagement-3.0.0-beta.pdf" cover_title: "Percona Monitoring and Management Documentation" - cover_subtitle: 3.0.0 (December 11, 2024) + cover_subtitle: 3.0.0 (December 13, 2024) author: "Percona Technical Documentation Team" cover_logo: docs/images/Percona_Logo_Color.png custom_template_path: resources/templates - enabled_if_env: ENABLE_PDF_EXPORT diff --git a/documentation/snippets/services-banner.md b/documentation/snippets/services-banner.md index a0e1d12dce..2c5d14caa1 100644 --- a/documentation/snippets/services-banner.md +++ b/documentation/snippets/services-banner.md @@ -1,4 +1,4 @@ -
+
## Get expert help { .title }