Skip to content

Commit 1f21e17

Browse files
patrickbirchpatrickbirch
committed
PS-10109 [DOCS] - Review and update apt-repo 8.4
 modified: docs/apt-pinning.md modified: docs/apt-repo.md
1 parent 212f6eb commit 1f21e17

File tree

7 files changed

+408
-85
lines changed

7 files changed

+408
-85
lines changed

‎docs/apt-download-deb.md

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,64 @@
1-
# Install Percona Server for MySQL {{vers}} using downloaded DEB packages
1+
# Install Percona Server for MySQL 8.4 using DEB packages
22

3-
Download the packages from [Percona Product Downloads](https://www.percona.com/downloads). If needed, [Instructions for the Percona Product Download](download-instructions.md) are available.
3+
Percona distributes DEB packages in tar bundles that contain multiple related packages. Two bundle types are available:
44

5-
The following example downloads Percona Server for MySQL {{release}} release packages for Ubuntu 22.04:
5+
* Full bundle: Contains all Percona Server packages including server, client, test packages, debug symbols, and source files
6+
7+
* Minimal bundle: Contains only the essential server and client packages needed for basic operation
8+
9+
Choose the bundle type based on your requirements. Download the bundle to access the components you need, then extract and install the individual DEB files using your system package manager.
10+
11+
## When to use this installation method
12+
13+
Advantages:
14+
15+
* Provides precise version control over installed packages
16+
17+
* Works in offline environments without internet access
18+
19+
* Allows installation before packages appear in standard repositories
20+
21+
* Enables administrators to validate packages before deployment
22+
23+
Disadvantages:
24+
25+
* Requires manual download and extraction steps
26+
27+
* Does not receive automatic updates through the package manager
28+
29+
* Users must manually track new releases and security updates
30+
31+
* Takes more time than repository-based installation
32+
33+
Download the bundle from Percona Product Downloads. Review the Instructions for the Percona Product Download if you need assistance.
34+
35+
This example downloads Percona Server for MySQL {{release}} release packages for Ubuntu 22.04:
636

737
```{.bash data-prompt="$"}
8-
$ wget https://downloads.percona.com/downloads/Percona-Server-8.4/Percona-Server-8.4.0-1/binary/debian/jammy/x86_64/Percona-Server-8.4.0-1-r238b3c02-jammy-x86_64-bundle.tar
38+
$ wget https://downloads.percona.com/downloads/Percona-Server-8.4/Percona-Server-{{release}}/binary/debian/jammy/x86_64/Percona-Server-{{release}}-[revision hash]-jammy-x86_64-bundle.tar
939
```
1040

11-
Unpack the download to get the packages:
41+
Extract the bundle to access the individual packages:
1242

1343
```{.bash data-prompt="$"}
14-
$ tar xvf Percona-Server-8.4.0-1-r71449379-buster-x86_64-bundle.tar
44+
$ tar xvf Percona-Server-{{release}}-[revision hash]-jammy-x86_64-bundle.tar
1545
```
16-
??? example "Expected output"
17-
18-
```text
19-
libperconaserverclient21_{{release}}-1.buster_amd64.deb
20-
libperconaserverclient21-dev_{{release}}-1.buster_amd64.deb
21-
percona-mysql-router_{{release}}-1.buster_amd64.deb
22-
percona-server-client_{{release}}-1.buster_amd64.deb
23-
percona-server-common_{{release}}-1.buster_amd64.deb
24-
percona-server-dbg_{{release}}-1.buster_amd64.deb
25-
percona-server-rocksdb_{{release}}-1.buster_amd64.deb
26-
percona-server-server_{{release}}-1.buster_amd64.deb
27-
percona-server-source_{{release}}-1.buster_amd64.deb
28-
percona-server-test_{{release}}-1.buster_amd64.deb
46+
47+
??? example "Expected output for a full tar extraction"
48+
49+
```{.text .no-copy}
50+
percona-server-server_{{release}}-1.jammy_amd64.deb
51+
percona-server-client_{{release}}-1.jammy_amd64.deb
52+
percona-server-common_{{release}}-1.jammy_amd64.deb
53+
percona-server-dbg_{{release}}-1.jammy_amd64.deb
54+
percona-server-source_{{release}}-1.jammy_amd64.deb
55+
percona-server-test_{{release}}-1.jammy_amd64.deb
2956
```
3057

31-
Install Percona Server for MySQL using `dpkg`. Run this command as root or use the sudo command:
58+
Install Percona Server for MySQL using the system package manager. Run this command as root or use sudo:
3259

3360
```{.bash data-prompt="$"}
34-
$ sudo dpkg -i *.deb
61+
$ sudo apt install ./*.deb
3562
```
3663

37-
!!! warning
38-
39-
When installing packages manually like this, you’ll need to resolve all the dependencies and install missing packages yourself. The following packages will need to be installed before you can manually install Percona Server: `mysql-common`, `libjemalloc1`, `libaio1`, and `libmecab2`.
64+
The package manager resolves dependencies automatically and installs all required components from the extracted files.

‎docs/apt-pinning.md

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,44 @@
11
# Apt pinning the Percona Server for MySQL {{vers}} packages
22

3-
Pinning allows you to stay on a release and get packages from a different version. In some cases, you can pin selected packages and avoid accidentally upgrading all the packages.
3+
Apt pinning helps you control which version of a package is installed from different repositories. This is useful when you want to stay on a specific release such as Percona Server for MySQL 8.4 and avoid automatic upgrades from other sources.
44

5-
The pinning takes place in the `preference` file. To pin a package, set the `Pin-Priority` to higher numbers.
6-
7-
Make a new file `/etc/apt/preferences.d/00percona.pref`. For example, add the following to the `preference` file:
5+
To pin the Percona Server for MySQL 8.4 packages, follow these steps:
6+
{.power-number}
87

9-
```text
10-
Package:
11-
Pin: release o=Percona Development Team
12-
Pin-Priority: 1001
13-
```
8+
1. Create a preferences file in `/etc/apt/preferences.d/` named `00percona.pref`:
149

15-
For more information about the pinning, you can check the official [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences).
10+
```{.bash data-prompt="$"}
11+
$ sudo nano /etc/apt/preferences.d/00percona.pref
12+
```
13+
14+
2. Add the pinning configuration content to the file:
15+
16+
```ini
17+
Package: percona-server-server
18+
Pin: release o=Percona Development Team,a=stable
19+
Pin-Priority: 1001
20+
```
21+
22+
* The `Package` field specifies the exact name of the package.
23+
* The `Pin` field identifies the origin of the package, which is the Percona repository.
24+
* The `Pin-Priority` field sets the priority level. A value above 1000 ensures this version is preferred over others.
25+
26+
Save and close the file.
27+
28+
3. Update package lists to refresh your package sources:
29+
30+
```{.bash data-prompt="$"}
31+
$ sudo apt update
32+
```
33+
34+
4. Install Percona Server for MySQL 8.4 using the following command:
35+
36+
```{.bash data-prompt="$"}
37+
$ sudo apt install percona-server-server
38+
```
39+
40+
Your system prioritizes the version from the Percona repository according to your pinning settings.
41+
42+
## Learn more
43+
44+
For additional details, visit the [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences).

‎docs/apt-repo.md

Lines changed: 19 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,59 @@
1-
# Use an APT repository to install Percona Server for MySQL {{vers}}
1+
# Install Percona Server for MySQL {{vers}} Using APT on Debian/Ubuntu
22

3-
Ready-to-use packages are available from the Percona Server for MySQL software
4-
repositories and the [Percona downloads] page.
3+
Percona provides ready-to-use packages for Percona Server for MySQL 8.4 through its APT repositories, offering seamless updates and dependency resolution for Debian-based systems.
54

6-
Specific information on the supported platforms, products, and versions is described in [Percona Software and Platform Lifecycle](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql).
5+
If you need help with installation or configuration, [Percona Support](https://www.percona.com/services/support) is available to assist you.
6+
7+
Specific information on the supported platforms, products, and versions are available in [Percona Software and Platform Lifecycle](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql).
8+
9+
Percona packages and Docker images collect anonymous telemetry data to improve product quality. For details on what is collected and how to opt out, see [Telemetry in Percona Server for MySQL].
710

8-
We gather [Telemetry data] in the Percona packages and Docker images.
911

10-
--8<--- "get-help-snip.md"
1112

1213
## ARM support
1314

14-
The DEB builds for Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, DEBIAN 11, and DEBIAN 12 contain ARM packages with the `aarch64.rpm` extension. This means that Percona Server for MySQL is available for users on ARM-based systems.
15+
Percona Server for MySQL 8.4 includes native support for the ARM64 (aarch64) architecture in its DEB packages. These packages are available for Ubuntu starting with version 20.04 and for Debian starting with version 11.
16+
1517

1618
## Install Percona Server for MySQL using APT
1719

1820
To install Percona Server for MySQL using APT, do the following steps:
1921
{.power-number}
2022

21-
1. Update the package repositories:
23+
1. Update the package index and install `curl`:
2224

2325
```{.bash data-prompt="$"}
24-
$ sudo apt update
26+
$ sudo apt update && sudo apt install curl
2527
```
2628

27-
2. Install the `curl` download utility if needed:
28-
29-
```{.bash data-prompt="$"}
30-
$ sudo apt install curl
31-
```
32-
33-
3. Download the `percona-release` repository package:
29+
2. Download the `percona-release` repository package:
3430

3531
```{.bash data-prompt="$"}
3632
$ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
3733
```
3834

39-
4. Install the downloaded package with `apt` as root or with sudo:
35+
3. Install the package with `apt` as root or with sudo:
4036

4137
```{.bash data-prompt="$"}
4238
$ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
4339
```
4440

45-
46-
5. Refresh the local cache to update the package information:
41+
4. Refresh the package index:
4742

4843
```{.bash data-prompt="$"}
4944
$ sudo apt update
5045
```
5146

52-
6. Use `percona-release` to set up the repository for the Percona Server for MySQL {{vers}} version:
47+
5. Enable the Percona Server for MySQL {{vers}} repository:
5348

5449
```{.bash data-prompt="$"}
5550
$ sudo percona-release enable-only {{pkg}} release
5651
$ sudo percona-release enable tools release
5752
```
5853

59-
7. You can check the repository setup for the Percona original release list in `/etc/apt/sources.list.d/percona-original-release.list`.
54+
6. [Optional] You can check the repository setup for the Percona original release list in ```cat /etc/apt/sources.list.d/percona-original-release.list```.
6055

61-
8. Install the server package with the `percona-release` command:
56+
8. Install the server:
6257

6358
```{.bash data-prompt="$"}
6459
$ sudo apt install percona-server-server
@@ -68,7 +63,7 @@ See [Configuring Percona repositories with `percona-release`](https://docs.perco
6863

6964
--8<--- "storage-engines.md"
7065

71-
Percona Server for MySQL includes user-defined functions (UDFs) from [Percona Toolkit](https://docs.percona.com/percona-toolkit/). These UDFs, `fnv_64`, `fnv1a_64`, `murmur_hash`, offer faster checksum calculations compared to standard methods. For detailed information about these user-defined functions, see [Percona Toolkit UDF functions](udf-percona-toolkit.md).
66+
Percona Server for MySQL includes user-defined functions (UDFs) from [Percona Toolkit](https://docs.percona.com/percona-toolkit/) for faster checksum calculations. Learn more in [Percona Toolkit UDF functions](udf-percona-toolkit.md).
7267

7368
Once the installation completes, execute the following command to install these functions:
7469

@@ -89,4 +84,4 @@ These builds should not be run in production. This build may not contain all of
8984

9085
[Percona downloads]: https://www.percona.com/downloads/Percona-Server-{{vers}}/
9186

92-
[Telemetry data]: telemetry.md
87+
[Telemetry in Percona Server for MySQL]: telemetry.md

‎docs/build-apt-packages.md

Lines changed: 49 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,59 @@
1-
# Build APT packages
1+
# Build DEB packages from source
22

3-
If you wish to build your own Debian/Ubuntu (dpkg) packages of Percona Server for MySQL,
4-
you first need to start with a source tarball, either from the Percona
5-
website or by generating your own by following the instructions above ([Installing Percona Server for MySQL from the Git Source Tree](source-tarball.md)).
3+
Build custom DEB packages when you need specific configuration options, patches, or want to create packages for distribution. This process compiles Percona Server from source code and creates installable DEB files.
4+
5+
## When to build from source
6+
7+
Advantages:
8+
9+
Enables custom compilation flags and configuration options
10+
11+
* Allows integration of custom patches or modifications
12+
13+
* Creates packages tailored for specific hardware or requirements
14+
15+
* Provides control over included features and dependencies
16+
17+
Disadvantages:
18+
19+
* Requires significant build time and system resources
20+
21+
* Demands expertise in Debian packaging and build tools
22+
23+
* Creates maintenance overhead for updates and security patches
24+
25+
* May introduce stability risks from custom modifications
26+
27+
## Prerequisites
28+
29+
Install the required build tools and dependencies:
30+
31+
```{.bash data-prompt="$"}
32+
$ sudo apt install build-essential devscripts debhelper sbuild
33+
$ sudo apt build-dep percona-server-server
34+
```
35+
36+
## Build process
37+
38+
Start with a source tarball from the Percona website or generate your own following the Git source tree installation instructions.
639

740
Extract the source tarball:
841

942
```{.bash data-prompt="$"}
10-
$ tar xfz Percona-Server-{{release}}-Linux.x86_64.ssl102.tar.gz
43+
$ tar xfz Percona-Server-{{release}}-Linux.x86_64.tar.gz
1144
$ cd Percona-Server-{{release}}
1245
```
1346

14-
Copy the Debian packaging in the directory that Debian expects it to be in:
47+
Copy the Debian packaging files to the expected directory structure:
1548

1649
```{.bash data-prompt="$"}
1750
$ cp -ap build-ps/debian debian
1851
```
19-
<!-- Do we need this part --->
20-
Update the changelog for your distribution (here we update for the unstable
21-
distribution - sid), setting the version number appropriately. The trailing one
22-
in the version number is the revision of the Debian packaging.
52+
53+
Update the changelog for your target distribution. This example updates for the unstable distribution (sid) and sets the version number. The trailing number represents the Debian packaging revision:
2354

2455
```{.bash data-prompt="$"}
25-
$ dch -D unstable --force-distribution -v "8.0.13-3-1" "Update to 8.0.13-3"
56+
$ dch -D unstable --force-distribution -v "{{release}}-1" "Update to {{release}}"
2657
```
2758

2859
Build the Debian source package:
@@ -31,15 +62,16 @@ Build the Debian source package:
3162
$ dpkg-buildpackage -S
3263
```
3364

34-
Use sbuild to build the binary package in a chroot:
65+
Use sbuild to create the binary package in a clean chroot environment:
3566

3667
```{.bash data-prompt="$"}
37-
$ sbuild -d sid percona-server-{{vers}}_{{release}}.dsc
68+
$ sbuild -d sid percona-server-8.4_{{release}}.dsc
3869
```
3970

40-
You can give different distribution options to `dch` and `sbuild` to build binary
41-
packages for all Debian and Ubuntu releases.
42-
4371
!!! note
4472

45-
[PAM Authentication Plugin](pam-plugin.md) is not built with the server by default. In order to build the Percona Server for MySQL with PAM plugin, an additional option `-DWITH_PAM=ON` should be used.
73+
The PAM Authentication Plugin does not build with the server by default. Add the `-DWITH_PAM=ON` option to build Percona Server for MySQL with PAM plugin support.
74+
75+
## Distribution compatibility
76+
77+
Pass different distribution options to `dch` and `sbuild` commands to build binary packages for various Debian and Ubuntu releases. Replace `sid` with your target distribution codename (such as `bookworm`, `jammy`, or `focal`).

0 commit comments

Comments
 (0)