PXB-3803 [DOCS] - [feedback] PXB 8.4 Quickstart, Restore the backup

docs/docker.md

@@ -105,3 +105,7 @@ sudo docker run --name percona-xtrabackup --volumes-from percona-server-mysql \
 percona/percona-xtrabackup
 xtrabackup --backup --data-dir=/var/lib/mysql --target-dir=/backup --user=root --password=mysql
 ```
+
+## Next step
+
+For a complete workflow including backup validation and disaster recovery, see the [Docker Compose tutorial](docker-compose-tutorial.md).

docs/quickstart-docker.md

@@ -1,17 +1,44 @@
-# Start a Docker container and take a backup
+# Take a backup with Docker
 
-In this scenario, Percona XtraBackup works in combination with a MySQL-compatible database instance. To use the tool, you must run Percona XtraBackup in a separate Docker container and then connect the Percona XtraBackup container directly to the Percona Server for MySQL container. This connection lets the backup tool access the database for backup and restore operations.
+This tutorial describes how to create a backup volume, run Percona XtraBackup in a Docker container, and take a prepared backup of a Percona Server for MySQL database.
 
-The following steps create a Docker volume, start Percona XtraBackup in a Docker container, take and prepare a backup of Percona Server for MySQL database.
-{.power-number}
+## Learning objectives
 
-## Create a Docker volume
+This tutorial covers the following tasks:
 
-The benefits of using a Docker volume are the following:
+* Create a Docker volume to store backup files
 
-* 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. 
+* Connect Percona XtraBackup to a running Percona Server container
 
-* You can quickly backup and restore your data using the `docker cp` command or mount the volume to another container.
+* Take a full backup using `xtrabackup --backup`
+
+* Prepare the backup using `xtrabackup --prepare`
+
+## Prerequisites
+
+Complete the following steps before starting this tutorial:
+
+* [Install Docker :octicons-link-external-16:](https://docs.docker.com/engine/install/) on your system
+
+* [Start Percona Server in a Docker container :octicons-link-external-16:](https://docs.percona.com/percona-server/{{vers}}/quickstart-docker.html) - Creates the `psmysql` container with the `mydb` database and `employees` table
+
+## Architecture overview
+
+Percona XtraBackup runs in a separate Docker container and connects to the Percona Server for MySQL container. This connection allows the backup tool to access the database files for backup and restore operations.
+
+For more information about how Percona XtraBackup works, see [How Percona XtraBackup works](how-xtrabackup-works.md).
+
+## Step 1: Create a backup volume
+
+Docker volumes provide persistent storage that remains accessible across container restarts and updates. Creating a dedicated backup volume offers the following benefits:
+
+* Data persists independently of container lifecycle
+
+* Multiple containers can access the same backup data
+
+* Backup files remain available for restore operations
+
+Create the backup volume with the following command:
 
 ```shell
 docker volume create backupvol
@@ -20,62 +47,53 @@ docker volume create backupvol
 ??? example "Expected output"
 
     ```{.text .no-copy}
-     backupvol
+    backupvol
     ```
 
-## Start Percona XtraBackup 8.4 in a container, take and prepare a backup
+## Step 2: Take and prepare the backup
 
-The `docker run` command creates and runs a new container from an image. The command modifies the container's behavior with options.
+The backup process requires connecting the Percona XtraBackup container to the Percona Server container. The `--user root` option grants the necessary permissions to access the MySQL data directory.
 
-In our example, the command has the following options:
+### Understand the command 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 automatically 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.|
+The following table describes each option used in the backup command:
 
-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  :octicons-link-external-16:](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. 
+| Option | Description |
+|--------|-------------|
+| `--name pxb` | Assigns the name `pxb` to the container |
+| `--volumes-from psmysql` | Mounts volumes from the `psmysql` container to access database files |
+| `-v backupvol:/backup_84` | Mounts the `backupvol` volume at `/backup_84` inside the container |
+| `-it` | Allocates a pseudo-terminal for interactive password entry |
+| `--user root` | Runs the container as root to access the MySQL data directory |
+| `--password` | Prompts for the MySQL root password |
 
-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:
+### Run the backup 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.              |
+Select the command for your system architecture:
 
-You can run the Docker ARM64 version of Percona XtraBackup. Use the `8.4-aarch64` tag instead of `8.4`.
+=== "AMD64 (Intel/AMD)"
 
-### Connect the Percona XtraBackup container to the Percona Server container
+    ```shell
+    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"
+    ```
 
-We recommend using the `–-user root` option in the Docker command.
-Run a Docker container example
+=== "ARM64 (Apple Silicon Macs)"
 
-```shell
-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"
-```
+    ```shell
+    docker run --name pxb --volumes-from psmysql -v backupvol:/backup_84 -it --user root percona/percona-xtrabackup:8.4-aarch64 /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`.
+Enter the password `secret` when prompted:
 
 ```{.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
@@ -87,23 +105,49 @@ In this example of expected output, we provide the first and last section of the
     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 executes two xtrabackup operations:
 
-The command then executes two steps: 
-
-* Runs `xtrabackup` with the `--backup` option to copy the data files from `/var/lib/mysql/` to `/backup_84`
-
-* Runs `xtrabackup` with the `--prepare` option to apply the log files and make the backup consistent and ready for restore
+* `xtrabackup --backup` - Copies data files from `/var/lib/mysql/` to `/backup_84`
+
+* `xtrabackup --prepare` - Applies transaction logs to make the backup consistent
+
+For more information about the backup and prepare process, see [Create a full backup](create-full-backup.md) and [Prepare a full backup](prepare-full-backup.md).
+
+!!! warning "Password visibility"
+
+    Specifying the password directly with `--password=secret` exposes the password in `docker ps`, `docker history`, and system process listings. Use the interactive prompt for production environments.
 
-You can check the Xtrabackup logs with the `docker container logs <container-name>` command.
+## Step 3: Verify the backup
 
-For example:
+Check the backup container logs to confirm the backup completed:
 
 ```shell
 docker container logs pxb
 ```
 
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    ...
+    2024-10-07T13:55:55.550829-00:00 0 [Note] [MY-011825] [Xtrabackup] completed OK!
+    ```
+
+The message `completed OK!` confirms the backup and prepare operations finished.
+
+## Summary
+
+This tutorial covered the following completed tasks:
+
+* Created the `backupvol` Docker volume for backup storage
+
+* Connected the Percona XtraBackup container to the `psmysql` database container
+
+* Executed `xtrabackup --backup` to copy database files
+
+* Executed `xtrabackup --prepare` to make the backup consistent
+
+The backup stored in `backupvol` is ready for restoration.
+
 ## Next steps
 
 [Restore the backup](quickstart-restore-back.md){.md-button}
-