Skip to content

Commit

Permalink
PXB-3216 Update Docker docs with information from QuickStart developm…
Browse files Browse the repository at this point in the history 
…ent (#303)

modified:   docs/docker.md
	modified:   docs/quickstart-docker.md
  • Loading branch information
@alina-derkach-oaza
alina-derkach-oaza authored Jul 17, 2024
1 parent 47e3ae9 commit a436bf8
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 120 deletions.
100 changes: 35 additions & 65 deletions docs/docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,38 @@
# Run Percona XtraBackup 8.0 in a Docker container

Docker allows you to run applications in a lightweight unit called a
container.
Docker containers are built from Docker images, which are snapshots of the configuration needed to run an applications, such as the code, and libraries. 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. You may run Percona Server for MySQL in one container and Percona XtraBackup in another.

You can run *Percona XtraBackup* in a Docker container without installing
the product. All required libraries are available in
the container. Being a lightweight execution environment, Docker containers
enable creating configurations where each program runs in a separate container. You may run
*Percona Server for MySQL* in one container and *Percona XtraBackup* in
another. Docker images offer a range of options.
For this document, container refers to the Docker container and instance refers to the database server in the container.

Create a Docker container based on a Docker image. Docker images for
Percona XtraBackup are hosted publicly on [Docker Hub](https://hub.docker.com/r/percona/percona-xtrabackup).
Percona XtraBackup has an official Docker image hosted on [Docker Hub](https://hub.docker.com/r/percona/percona-xtrabackup/). If you want the latest version, use the `latest` tag. You can reference a specific version using the [Docker tag filter for the 8.0 versions](https://registry.hub.docker.com/r/percona/percona-xtrabackup/tags?page=1&name=8.0).

```{.bash data-prompt="$"}
$ sudo docker create ... percona/percona-xtrabackup --name xtrabackup ...
```

### Scope of this section

This section demonstrates how to back up data
on a Percona Server for MySQL running in another Dockers container.

## 1. Install Docker

Your operating system may already provide a package for *docker*. However,
the versions of Docker provided by your operating system are likely to be
outdated.

Use the installation instructions for your operating system available from
the Docker site to set up the latest version of *docker*.
Make sure that you are using the latest version of Docker. The `APT` and `YUM` versions may be outdated and cause errors. Use the [installation instructions](https://docs.docker.com/engine/install/) to install Docker on your system.

## 2. Connect to a Percona Server for MySQL container

Percona XtraBackup works in combination with a database server. When
running a Docker container for Percona XtraBackup, you can make
backups for a database server either installed on the host machine or
running in a separate Docker container.

To set up a database server on a host machine or in Docker
container, follow the documentation of the supported product that you
intend to use with *Percona XtraBackup*.

!!! admontion "See also"

[Docker volumes as container persistent data storage](https://docs.docker.com/storage/volumes/)

[More information about containers](https://docs.docker.com/config/containers/start-containers-automatically)

```{.bash data-prompt="$"}
$ sudo docker run -d --name percona-server-mysql \
-e MYSQL_ROOT_PASSWORD=root percona/percona-server:8.0
```
## 1. Run Percona Server for MySQL container

As soon as Percona Server for MySQL runs, add some data to it. Now, you are
ready to make backups with Percona XtraBackup.
Percona XtraBackup works in combination with a MySQL-compatible database, Percona Server for MySQL, in our example. To take a backup of Percona Server for MySQL, run Percona Server for MySQL in a Docker container and create a database with data. Read the instructions on how to [Run Percona Server for MySQL in a Docker Container](https://docs.percona.com/percona-server/8.0/docker.html).

!!! important

When running Percona XtraBackup from a container and connecting to a
MySQLserver container, we recommend using the –user root option in the
Docker command.
As soon as Percona Server for MySQL runs and the database contains data, you are ready to connect the Percona XtraBackup container to the Percona Server for MySQL container and take a backup.

## 3. Create a Docker container from Percona XtraBackup image
## 2. Create Percona XtraBackup Docker container and connect to Percona Server for MySQL container

You can create a Docker container based on Percona XtraBackup image with
either `docker create` or the `docker run` command. `docker create`
creates a Docker container and makes it available for starting later.

Docker downloads the Percona XtraBackup image from the Docker Hub. If it
Docker downloads the Percona XtraBackup 8.0 image from the Docker Hub. If it
is not the first time you use the selected image, Docker uses the image
available locally.

!!! important

When running Percona XtraBackup from a container and connecting to a
MySQLserver container, we recommend using the --user=root option in the
Docker command.

```{.bash data-prompt="$"}
$ sudo docker create --name percona-xtrabackup --volumes-from percona-server-mysql \
percona/percona-xtrabackup \
$ sudo docker create --name percona-xtrabackup --volumes-from percona-server-mysql:8.0 \
percona/percona-xtrabackup:8.0 \
xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/backup \
--user=root --password=root
```
Expand All @@ -85,22 +43,34 @@ so that you could easily locate it among your other containers.
The `volumes-from` flag refers to Percona Server for MySQL and indicates
that you intend to use the same data as the Percona Server for MySQL container.

Run the container with exactly the same parameters that were used when the
container was created:
### Percona XtraBackup ARM64

Starting with Percona XtraBackup 8.0.35-31, you can run the Docker ARM64 version of Percona XtraBackup. You can find the version and architecture on [Docker Hub Percona/Percona-Server Tags](https://registry.hub.docker.com/r/percona/percona-xtrabackup/tags?page=1&name=8.0). The Docker images for ARM64 version contain `aarch64` in the tag name, for example, `8.0.35-aarch64`.

We recommend that the architectures match. If the server is ARM64, you should also use Percona XtraBackup in ARM64.

### Start the Percona XtraBackup container

Start the Percona XtraBackup container with exactly the same parameters that were used when the container was created:

```{.bash data-prompt="$"}
$ sudo docker start -ai percona-xtrabackup
```

This command starts the *percona-xtrabackup* container, attaches to its
This command starts the `percona-xtrabackup` container, attaches to its
input/output streams, and opens an interactive shell.

The `docker run` is a shortcut command that creates a Docker container and
### Docker run command

The `docker run` command is a shortcut command that creates a Docker container and
then immediately runs it.

```{.bash data-prompt="$"}
$ sudo docker run --name percona-xtrabackup --volumes-from percona-server-mysql \
percona/percona-xtrabackup
$ sudo docker run --name percona-xtrabackup --volumes-from percona-server-mysql:8.0 \
percona/percona-xtrabackup:8.0
xtrabackup --backup --datadir=/var/lib/mysql --target-dir=/backup --user=root --password=root
```

## For more information

Review the [Docker Docs](https://docs.docker.com/)
120 changes: 65 additions & 55 deletions docs/quickstart-docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,93 +5,103 @@ Percona XtraBackup works in combination with a MySQL-compatible database, Percon
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}

1. Create a Docker volume
## Create a Docker volume

One of the benefits of using a Docker volume for persistent storage with a database is that it allows you to 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. Another benefit is that you can quickly backup and restore your data using the docker cp command or mount the volume to another container.
The benefits of using a Docker volume are the following:

```{.bash data-prompt="$"}
$ docker volume create backupvol
```
* 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"
??? example "Expected output"

```{.text .no-copy}
backupvol
```

## Start Percona XtraBackup 8.0.34 in a container, take and prepare a backup

```{.text .no-copy}
backupvol
```
The `docker run` command creates and runs a new container from an image. The command modifies the container's behavior with options.

2. Start Percona XtraBackup 8.0.34 in a container, take and prepare a backup
In our example, the command has the following options:

The `docker run` command creates and runs a new container from an image. The command modifies the container's behavior with 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_8034` |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.0.34` | Use this tag to specify a specific version. Avoid using the `latest` tag. <br> In our example, we use the `8.0.34` tag. In Docker, a tag is a label assigned to an image and is used to maintain different versions of an image.|

In our example, the command has the following options:
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.0.34, 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` | 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_8034` |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.0.34` | Use this tag to specify a specific version. Avoid using the `latest` tag. <br> In our example, we use the `8.0.34` tag. In Docker, a tag is a label assigned to an image and is used to maintain different versions of an image.|
Starting with Percona XtraBackup 8.0.35-31, you can run the Docker ARM64 version of Percona XtraBackup. Use the `8.0.35-31-aarch64` tag instead of `8.0.35-31`.

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. The usage of tags ensures that you use [compatible versions](quickstart-overview.md#limitations) of Percona Server for MySQL and Percona XtraBackup.
### Connect the Percona XtraBackup container to the Percona Server container

To connect the Percona XtraBackup container to the Percona Server container, we recommend using the `–-user root` option in the Docker command.
We recommend using the `–-user root` option in the Docker command.

* Run a Docker container example
Run a Docker container example

```{.bash data-prompt="$"}
$ docker run --name pxb --volumes-from psmysql -v backupvol:/backup_8034 -it --user root percona/percona-xtrabackup:8.0.34 /bin/bash -c "xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/backup_8034 --user=root --password; xtrabackup --prepare --target-dir=/backup_8034"
```
```{.bash data-prompt="$"}
$ docker run --name pxb --volumes-from psmysql -v backupvol:/backup_8034 -it --user root percona/percona-xtrabackup:8.0.34 /bin/bash -c "xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/backup_8034 --user=root --password; xtrabackup --prepare --target-dir=/backup_8034"
```

You are prompted to enter the password, which is `secret`, in our example.
You are prompted to enter the password. In our example, the password is `secret`.

```{.text .no-copy}
2023-12-21T16:16:10.796716-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized server arguments: --datadir=/var/lib/mysql/2023-12-21T16:16:10.799979-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized client arguments: --backup=1 --target-dir=/backup_8034 --user=root --password
```{.text .no-copy}
2023-12-21T16:16:10.796716-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized server arguments: --datadir=/var/lib/mysql/2023-12-21T16:16:10.799979-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized client arguments: --backup=1 --target-dir=/backup_8034 --user=root --password
Enter 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.
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"
??? example "Expected output"

```{.text .no-copy}
```{.text .no-copy}

2023-12-14T15:45:16.277503-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized server arguments: --datadir=/var/lib/mysql/
2023-12-14T15:45:16.277503-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized server arguments: --datadir=/var/lib/mysql/

2023-12-14T15:45:16.280208-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized client arguments: --backup=1 --target-dir=/backup_80 --user=root --password=*
2023-12-14T15:45:16.280208-00:00 0 [Note] [MY-011825] [Xtrabackup] recognized client arguments: --backup=1 --target-dir=/backup_80 --user=root --password=*

xtrabackup version 8.0.34-29 based on MySQL server 8.0.34 Linux (x86_64) (revision id: 5ba706ee)
xtrabackup version 8.0.34-29 based on MySQL server 8.0.34 Linux (x86_64) (revision id: 5ba706ee)

2023-12-14T15:45:16.306670-00:00 0 [Note] [MY-011825] [Xtrabackup] perl binary not found. Skipping the version check
2023-12-14T15:45:16.306670-00:00 0 [Note] [MY-011825] [Xtrabackup] perl binary not found. Skipping the version check

2023-12-14T15:45:16.307026-00:00 0 [Note] [MY-011825] [Xtrabackup] Connecting to MySQL server host: localhost, user: root, password: set, port: not set, socket: not set
2023-12-14T15:45:16.307026-00:00 0 [Note] [MY-011825] [Xtrabackup] Connecting to MySQL server host: localhost, user: root, password: set, port: not set, socket: not set

2023-12-14T15:45:16.320214-00:00 0 [Note] [MY-011825] [Xtrabackup] Using server version 8.0.34-26
2023-12-14T15:45:16.320214-00:00 0 [Note] [MY-011825] [Xtrabackup] Using server version 8.0.34-26
...
...

2023-12-14T15:45:20.619892-00:00 0 [Note] [MY-011825] [Xtrabackup] completed OK!
```

2023-12-14T15:45:20.619892-00:00 0 [Note] [MY-011825] [Xtrabackup] completed OK!
```
The command runs a Docker container `pxb` from the `percona/percona-xtrabackup:8.0.34` 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 runs a Docker container `pxb` from the `percona/percona-xtrabackup:8.0.34` 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:
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 `--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
* 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.
You can check the Xtrabackup logs with the `docker container logs <container-name>` command.

For example:
For example:

```{.bash data-prompt="$"}
$ docker container logs pxb
```
```{.bash data-prompt="$"}
$ docker container logs pxb
```

## Next steps

Expand Down

0 comments on commit a436bf8

Please sign in to comment.