Merge pull request #330 from percona/pxb-3364

PXB-3364 Add Quickstart for PXB 8.4 version

docs/quickstart-docker.md

@@ -0,0 +1,109 @@
+# Start a Docker container and take a backup
+
+Percona XtraBackup works in combination with a MySQL-compatible database, Percona Server for MySQL, in our scenario. To use Percona XtraBackup, run it in a separate Docker container and then connect the Percona XtraBackup container to the Percona Server for MySQL container. As soon as you [start Percona Server for MySQL in a Docker container](https://docs.percona.com/percona-server/8.4/quickstart-docker.html) and [create a database and table in Percona Server for MySQL](https://docs.percona.com/percona-server/8.4/quickstart-docker.html#create-a-database), you are ready to backup your databes with Percona XtraBackup.
+
+The following steps create a Docker volume, start Percona XtraBackup in a Docker continer, take and prepare a backup of Percona Server for MySQL database.
+{.power-number}
+
+## Create a Docker volume
+
+The benefits of using a Docker volume are the following:
+
+* You can keep your data safe and accessible across different containers. For example, if you want to upgrade your database image to a newer version, you can stop the old container and start a new one with the same volume attached without losing any data. 
+
+* You can quickly backup and restore your data using the `docker cp` command or mount the volume to another container.
+
+```{.bash data-prompt="$"}
+$ docker volume create backupvol
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+     backupvol
+    ```
+
+## Start Percona XtraBackup 8.4 in a container, take and prepare a backup
+
+The `docker run` command creates and runs a new container from an image. The command modifies the container's behavior with options.
+
+In our example, the command has the following options:
+
+| Option | Description |
+|---|---|
+| `--name`  |  Provides a name to the container. If you do not use this option, Docker adds a random name.  |
+| `--volumes-from` | Refers to Percona Server for MySQL and indicates that you intend to use the same data as the `psmysql` container.|
+| `it` | Interacts with the container and be a pseudo-terminal. |
+| `--user root` | Sets the user to root inside the Percona XtraBackup container. This option is required to access the MySQL data directory and run the xtrabackup command. |
+|`backup_84` |Indicates the directory inside the container where the backup files are stored. |
+| `-v` | Mounts a volume from the host machine to volumes in another container that is being run. In our example, the `-v` option mounts a volume from the `psmysql` container to the `backupvol` volume on the host machine.|
+| `backupvol` | Indicates the persistent storage for the database. |
+| `psmysql`    | Indicates the Percona Server for MySQL container.  |
+|`--password`   | Prompts the user to enter the password for the root user. For convenience you can add the password for the root user to this option, for example, `--password=secret`. Then the password will be passed automaticaly when running the command. Note that if you specify the password with `--password=secret`, the password is visible in `docker ps`, `docker ps -a` (docker history) and regular ps command.          |
+| `8.4` | Use this tag to specify a specific version. Avoid using the `latest` tag. <br> In our example, we use the `8.4` tag. In Docker, a tag is a label assigned to an image and is used to maintain different versions of an image.|
+
+If you do not add a tag, Docker uses `latest` as the default tag and downloads the newest image from [percona/percona-xtrabackup on the Docker Hub](https://hub.docker.com/r/percona/percona-xtrabackup). This image can be in a different series or version from what you expect since the latest image changes over time. If you are using Percona XtraBackup version prior to 8.4, use tags to ensure that you use [compatible versions](server-backup-version-comparison.md) of Percona Server for MySQL and Percona XtraBackup. 
+
+The CPU architecture or platform for Percona Server for MySQL and Percona XtraBackup should be the same. If you want to use a different platform, you can add the following command:
+
+| Platform                 | Description                                                 |
+|--------------------------|-------------------------------------------------------------|
+| --platform linux/amd64    | To run an AMD64 platform on an ARM64 computer.              |
+| --platform linux/arm64    | To run an ARM64 platform on an AMD64 computer.              |
+
+You can run the Docker ARM64 version of Percona XtraBackup. Use the `8.4-aarch64` tag instead of `8.4`.
+
+### Connect the Percona XtraBackup container to the Percona Server container
+
+We recommend using the `–-user root` option in the Docker command.
+Run a Docker container example
+
+```{.bash data-prompt="$"}
+$ docker run --name pxb --volumes-from psmysql -v backupvol:/backup_84 -it --user root percona/percona-xtrabackup:8.4 /bin/bash -c "xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/backup_84 --user=root --password; xtrabackup --prepare --target-dir=/backup_84"
+```
+
+You are prompted to enter the password. In our example, the password is `secret`.
+
+```{.text .no-copy}
+2024-10-07T13:55:47.640100-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized server arguments: --datadir=/var/lib/mysql/
+2024-10-07T13:55:47.641887-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized client arguments: --backup=1 --target-dir=/backup_84 --user=root --password
+Enter password:
+```
+
+In this example of expected output, we provide the first and last section of the backup log and use ellipses instead of the entire backup log.
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+
+    xtrabackup version 8.4.0-1 based on MySQL server 8.4.0 Linux (x86_64) (revision id: 3792f907)
+    2024-10-07T13:55:51.255518-00:00 0 [Note] [MY-011825] [Xtrabackup] perl binary not found. Skipping the version check
+    2024-10-07T13:55:51.256080-00:00 0 [Note] [MY-011825] [Xtrabackup] Connecting to MySQL server host: localhost, user: root, password: set, port: not set, socket: not set
+    2024-10-07T13:55:51.270222-00:00 0 [Note] [MY-011825] [Xtrabackup] Using server version 8.4.0-1
+    2024-10-07T13:55:51.272839-00:00 0 [Note] [MY-011825] [Xtrabackup] Executing LOCK TABLES FOR BACKUP
+        
+    ...
+
+    2024-10-07T13:55:55.550829-00:00 0 [Note] [MY-011825] [Xtrabackup] completed OK!
+    ```
+
+The command runs a Docker container `pxb` from the `percona/percona-xtrabackup:8.4` image and mounts two volumes: one from another container named `psmysql`, which contains Percona Server data directory, and another named `backupvol`, which is where the backup files are stored. The command also sets the user to root and prompts the user to enter the password. 
+
+The command then executes two steps: 
+
+* Runs `xtrabackup` with the `--backup` option to copy the data files from `/var/lib/mysql/` to `/backup_8034`
+
+* Runs `xtrabackup` with the `--prepare` option to apply the log files and make the backup consistent and ready for restore
+
+You can check the Xtrabackup logs with the `docker container logs <container-name>` command.
+
+For example:
+
+```{.bash data-prompt="$"}
+$ docker container logs pxb
+```
+
+## Next steps
+
+[Restore the backup :material-arrow-right:](quickstart-restore-backup.md){.md-button}
+

docs/quickstart-next-steps.md

@@ -0,0 +1,33 @@
+# Next steps
+
+After you take your first backup with Percona Xtrabackup, it's high time to expand your knowledge and skills in using Percona Xtrabackup.
+
+Review the [Percona Xtrabackup documentation](https://docs.percona.com/percona-xtrabackup/8.0/) for more information.
+
+## Learn more about other Percona products
+
+### For superior and optimized performance
+
+Percona Server for MySQL (PS) is a freely available, fully compatible, enhanced, and open source drop-in replacement for any MySQL database. It provides superior and optimized performance, greater scalability and availability, enhanced backups, increased visibility, and instrumentation. Percona Server for MySQL is trusted by thousands of enterprises to provide better performance and concurrency for their most demanding workloads.
+
+Install [Percona Server for MySQL](https://docs.percona.com/percona-server/8.0/installation.html).
+
+### For high availability
+
+Percona XtraDB Cluster (PXC) is a 100% open source, enterprise-grade, highly available clustering solution for MySQL multi-master setups based on Galera. PXC helps enterprises minimize unexpected downtime and data loss, reduce costs, and improve performance and scalability of your database environments supporting your critical business applications in the most demanding public, private, and hybrid cloud environments. 
+
+Install [Percona XtraDB Cluster](https://docs.percona.com/percona-xtradb-cluster/8.0/install-index.html).
+
+### For Monitoring and Management
+
+Percona Monitoring and Management (PMM) monitors and provides actionable performance data for MySQL variants, including Percona Server for MySQL, Percona XtraDB Cluster, Oracle MySQL Community Edition, Oracle MySQL Enterprise Edition, and MariaDB. PMM captures metrics and data for the InnoDB, XtraDB, and MyRocks storage engines, and has specialized dashboards for specific engine details.
+
+[Install PMM and connect your MySQL instances to it](https://docs.percona.com/percona-monitoring-and-management/get-started/index.html).
+
+### Advanced command-line tools
+
+Percona Toolkit is a collection of advanced command-line tools used by the Percona support staff to perform a variety of MySQL, MongoDB, and system tasks that are complex or difficult to perform manually. These tools are ideal alternatives to “one-off” scripts because they are professionally developed, formally tested, and documented. Each tool is self-contained, so installation is quick and easy and does not install libraries.
+
+[Percona Toolkit documentation](https://docs.percona.com/percona-toolkit/)
+
+[Install PMM and connect your MySQL instances to it](https://docs.percona.com/percona-monitoring-and-management/get-started/index.html).

docs/quickstart-overview.md

@@ -1,38 +1,65 @@
-# Quickstart Guide for Percona XtraBackup {{vers}}
+# Quickstart Overview
 
-Percona XtraBackup (PXB) is a 100% open source backup solution for all versions of Percona Server for MySQL and MySQL® that performs online non-blocking, tightly compressed, highly secure full backups on transactional systems. Maintain fully available applications during planned maintenance windows with Percona XtraBackup.
+Percona XtraBackup is a 100% open source backup solution for all versions of Percona Server for MySQL and MySQL® that performs online non-blocking, tightly compressed, highly secure full backups on transactional systems.
 
-## Install Percona XtraBackup:
+To quickly start with Percona XtraBackup, we recommend using Docker. This Quickstart guide focuses on this installation method. You can explore alternative installation options in the [Install](installation.md) section.
 
-You can install Percona XtraBackup using different methods:
+### Docker containers
 
-* [Use the Percona Repositories](installation.md)
+Docker containers are built from Docker images, which are configuration snapshots needed to run applications. With Docker, you can build, deploy, run, update, and manage containers, which isolate applications from the host system. A Docker container lets you work with Percona XtraBackup without installing the product on a local drive.
 
-* [Use APT](apt-repo.md)
+Using Docker has benefits:
 
-* [Use YUM](yum-repo.md)
+* Easily set up and use
+* Doesn't change anything on your computer
+* Simply remove it when you're done
 
-* [Use binary tarballs](binary-tarball.md)
+## Quickstart Purpose
 
-* [Use Docker](docker.md)
+This section provides you with the basic steps to start Percona XtraBackup in a Docker container, take a backup, prepare a backup and restore a backup of Percona Server for MySQL database.
 
-## For superior and optimized performance
+We use specific names in our examples, but feel free to change them if you want. Just remember that if you do, your results might be different from our guide.
 
-Percona Server for MySQL (PS) is a freely available, fully compatible, enhanced, and open source drop-in replacement for any MySQL database. It provides superior and optimized performance, greater scalability and availability, enhanced backups, increased visibility, and instrumentation. Percona Server for MySQL is trusted by thousands of enterprises to provide better performance and concurrency for their most demanding workloads.
+When we talk about a "container," we mean the Docker container where Percona XtraBackup is running. When we say "instance," we're talking about the MySQL database server inside that container.
 
-Install [Percona Server for MySQL].
+This guide will help you get started quickly, but there's a lot more to learn about database backups as you go along.
 
-## For high availability
+## Prerequisites
 
-Percona XtraDB Cluster (PXC) is a 100% open source, enterprise-grade, highly available clustering solution for MySQL multi-source setups based on Galera. PXC helps enterprises minimize unexpected downtime and data loss, reduce costs, and improve performance and scalability of your database environments supporting your critical business applications in the most demanding public, private, and hybrid cloud environments. 
+* [Install Docker](https://docs.docker.com/engine/install/) on your system.
 
-Install [Percona XtraDB Cluster].
+To take a backup of Percona Server for MySQL, run Percona Server for MySQL in a Docker container and create a database, and a table.
 
-## For Monitoring and Management
+* [Start Percona Server in a Docker container](https://docs.percona.com/percona-server/8.4/quickstart-docker.html)
+* [Create a database and table in Percona Server](https://docs.percona.com/percona-server/8.4/quickstart-docker.html#create-a-database)
 
-Percona Monitoring and Management (PMM) monitors and provides actionable performance data for MySQL variants, including Percona Server for MySQL, Percona XtraDB Cluster, Oracle MySQL Community Edition, Oracle MySQL Enterprise Edition, and MariaDB. PMM captures metrics and data for the InnoDB, XtraDB, and MyRocks storage engines, and has specialized dashboards for specific engine details.
+### Limitations
 
-[Install PMM and connect your MySQL instances to it](https://docs.percona.com/percona-monitoring-and-management/get-started/index.html).
+Percona XtraBackup 8.4 does not support making backups of databases created in versions before the 8.4 series of MySQL, Percona Server for MySQL, or Percona XtraDB Cluster.
 
-[Percona Server for MySQL]: https://docs.percona.com/percona-server/innovation-release/installation.html
-[Percona XtraDB Cluster]: https://docs.percona.com/percona-xtradb-cluster/8.0/install-index.html
+### Support servers and storage engines
+
+Percona XtraBackup 8.4 supports backing up data from various MySQL-compatible servers and storage engines.
+
+Supported Servers:
+
+* MySQL Server
+* Percona Server for MySQL
+* Percona XtraDB Cluster
+
+Supported Storage Engines:
+
+* InnoDB
+* XtraDB
+* MyISAM
+* MyRocks
+
+## Steps to perform
+
+In this Quickstart, you will learn how to:
+{.power-number}
+
+1. [Start a Docker container and take a backup](quickstart-docker.md)
+2. [Restore a backup](quickstart-restore-backup.md)
+3. [Clean up](quickstart-exit.md)
+4. [Choose your next steps](quickstart-next-steps.md)