Skip to content

Commit 098dd9f

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #566 from percona/ps-10136
PS-10136 [DOCS] - Update apt-repo 8.4
2 parents c572986 + 2dd9f04 commit 098dd9f

File tree

3 files changed

+675
-49
lines changed

3 files changed

+675
-49
lines changed

‎docs/apt-repo.md‎

Lines changed: 299 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,23 @@ We gather [Telemetry data] in the Percona packages and Docker images.
1010

1111
--8<--- "get-help-snip.md"
1212

13+
Before proceeding with the installation, make sure you have one of the following:
14+
15+
* `sudo` access: Administrator privileges are necessary for installing packages and configuring system services.
16+
17+
* Root access: Certain commands will require root privileges or `sudo` access.
18+
1319
## ARM support
1420

15-
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.
21+
Percona supports DEB builds with ARM packages with the `aarch64.rpm` extension.
1622

1723
## Unattended installations
1824

1925
--8<-- "install-flag.md"
2026

21-
2227
## Install Percona Server for MySQL using APT
2328

24-
To install Percona Server for MySQL using APT, do the following steps:
29+
To install Percona Server for MySQL using APT, follow these steps:
2530
{.power-number}
2631

2732
1. Update the package repositories:
@@ -30,38 +35,200 @@ To install Percona Server for MySQL using APT, do the following steps:
3035
$ sudo apt update
3136
```
3237

33-
2. Install the `curl` download utility if needed:
38+
??? example "Expected output"
39+
40+
```{.text .no-copy}
41+
Hit:1 http://us.archive.ubuntu.com/ubuntu jammy InRelease
42+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
43+
Hit:3 http://us.archive.ubuntu.com/ubuntu jammy-backports InRelease
44+
Get:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [119 kB]
45+
Fetched 238 kB in 2s (119 kB/s)
46+
Reading package lists... Done
47+
Building dependency tree... Done
48+
Reading state information... Done
49+
All packages are up to date.
50+
```
51+
52+
If this step fails:
53+
54+
* Check your internet connection
55+
56+
* Ensure your system can reach Ubuntu/Debian repositories
57+
58+
* Try running `sudo apt update --fix-missing`
59+
60+
2. `curl` allows you to download files from the internet using command line. Install the `curl` download utility if needed:
61+
62+
3463

3564
```{.bash data-prompt="$"}
3665
$ sudo apt install curl
3766
```
38-
67+
68+
??? example "Expected output"
69+
70+
```{.text .no-copy}
71+
Reading package lists... Done
72+
Building dependency tree... Done
73+
Reading state information... Done
74+
The following NEW packages will be installed:
75+
curl
76+
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
77+
Need to get 185 kB of archives.
78+
After this operation, 504 kB of additional disk space will be used.
79+
Do you want to continue? [Y/n] y
80+
Get:1 http://us.archive.ubuntu.com/ubuntu jammy/main amd64 curl amd64 7.81.0-1ubuntu1.15 [185 kB]
81+
Fetched 185 kB in 1s (185 kB/s)
82+
Selecting previously unselected package curl.
83+
(Reading database ... 123456 files and directories currently installed.)
84+
Preparing to unpack .../curl_7.81.0-1ubuntu1.15_amd64.deb ...
85+
Unpacking curl (7.81.0-1ubuntu1.15) ...
86+
Setting up curl (7.81.0-1ubuntu1.15) ...
87+
Processing triggers for man-db (2.10.2-1) ...
88+
```
89+
90+
If this step fails:
91+
92+
* The `curl` package might already be installed
93+
94+
* Check if you have internet connectivity
95+
96+
* Try running `which curl` to see if it's already available
97+
3998
3. Download the `percona-release` repository package:
4099

41100
```{.bash data-prompt="$"}
42101
$ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
43102
```
44103

45-
4. Install the downloaded package with `apt` as root or with sudo:
104+
??? example "Expected output"
105+
106+
```{.text .no-copy}
107+
% Total % Received % Xferd Average Speed Time Time Time Current
108+
Dload Upload Total Spent Left Speed
109+
100 15.2k 100 15.2k 0 0 15.2k 0 0:00:01 0:00:01 --:--:-- 15.2k
110+
```
111+
112+
If this step fails:
113+
114+
* Check your internet connection
115+
116+
* Verify the URL is accessible: `curl -I https://repo.percona.com/apt/percona-release_latest.generic_all.deb`
117+
118+
* Try downloading from a different network if possible
119+
120+
4. `gnupg2` provides encryption and digital signature verification for package security. `lsb-release` provides information about your Linux distribution. These packages are required dependencies for the Percona repository setup. Install the downloaded package with `apt` as root or with sudo:
121+
122+
46123

47124
```{.bash data-prompt="$"}
48125
$ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
49126
```
50-
127+
128+
??? example "Expected output"
129+
130+
```{.text .no-copy}
131+
Reading package lists... Done
132+
Building dependency tree... Done
133+
Reading state information... Done
134+
The following NEW packages will be installed:
135+
gnupg2 lsb-release percona-release
136+
The following packages will be upgraded:
137+
(none)
138+
0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
139+
Need to get 1,245 kB of archives.
140+
After this operation, 3,456 kB of additional disk space will be used.
141+
Do you want to continue? [Y/n] y
142+
Get:1 http://us.archive.ubuntu.com/ubuntu jammy/main amd64 gnupg2 amd64 2.2.27-3ubuntu2.1 [1,234 kB]
143+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy/main amd64 lsb-release all 11.1.0ubuntu4 [11.0 kB]
144+
Get:3 ./percona-release_latest.generic_all.deb percona-release all 1.0-27.generic [15.2 kB]
145+
Fetched 1,245 kB in 2s (622 kB/s)
146+
Selecting previously unselected package gnupg2.
147+
(Reading database ... 123456 files and directories currently installed.)
148+
Preparing to unpack .../gnupg2_2.2.27-3ubuntu2.1_amd64.deb ...
149+
Unpacking gnupg2 (2.2.27-3ubuntu2.1) ...
150+
Selecting previously unselected package lsb-release.
151+
Preparing to unpack .../lsb-release_11.1.0ubuntu4_all.deb ...
152+
Unpacking lsb-release (11.1.0ubuntu4) ...
153+
Selecting previously unselected package percona-release.
154+
Preparing to unpack .../percona-release_latest.generic_all.deb ...
155+
Unpacking percona-release (1.0-27.generic) ...
156+
Setting up gnupg2 (2.2.27-3ubuntu2.1) ...
157+
Setting up lsb-release (11.1.0ubuntu4) ...
158+
Setting up percona-release (1.0-27.generic) ...
159+
Processing triggers for man-db (2.10.2-1) ...
160+
```
161+
162+
If this step fails:
163+
164+
* Ensure the downloaded file exists: `ls -la percona-release_latest.generic_all.deb`
165+
166+
* Check if the file is corrupted by downloading again
167+
168+
* Verify you have sufficient disk space: `df -h`
51169

52170
5. Refresh the local cache to update the package information:
53171

54172
```{.bash data-prompt="$"}
55173
$ sudo apt update
56174
```
57175

176+
??? example "Expected output"
177+
178+
```{.text .no-copy}
179+
Hit:1 http://us.archive.ubuntu.com/ubuntu jammy InRelease
180+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
181+
Hit:3 http://us.archive.ubuntu.com/ubuntu jammy-backports InRelease
182+
Get:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [119 kB]
183+
Get:5 https://repo.percona.com/apt jammy InRelease [15.2 kB]
184+
Fetched 253 kB in 2s (126 kB/s)
185+
Reading package lists... Done
186+
Building dependency tree... Done
187+
Reading state information... Done
188+
All packages are up to date.
189+
```
190+
191+
If this step fails:
192+
193+
* The repository might not be properly configured
194+
195+
* Check repository status: `sudo apt update 2>&1 | grep -i percona`
196+
197+
* Try running the percona-release setup again
198+
58199
6. Use `percona-release` to set up the repository for the Percona Server for MySQL {{vers}} version:
59200

60201
```{.bash data-prompt="$"}
61202
$ sudo percona-release enable-only {{pkg}} release
62203
$ sudo percona-release enable tools release
63204
```
64205

206+
??? example "Expected output"
207+
208+
```{.text .no-copy}
209+
* Enabling Percona Server for MySQL 8.4 LTS repository
210+
* Enabling Percona Tools repository
211+
* Running apt-get update...
212+
Hit:1 http://us.archive.ubuntu.com/ubuntu jammy InRelease
213+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
214+
Hit:3 http://us.archive.ubuntu.com/ubuntu jammy-backports InRelease
215+
Get:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [119 kB]
216+
Get:5 https://repo.percona.com/apt jammy InRelease [15.2 kB]
217+
Fetched 253 kB in 2s (126 kB/s)
218+
Reading package lists... Done
219+
Building dependency tree... Done
220+
Reading state information... Done
221+
All packages are up to date.
222+
```
223+
224+
If this step fails:
225+
226+
* Check if percona-release is properly installed: `which percona-release`
227+
228+
* Verify the package name is correct for your version
229+
230+
* Check for any error messages in the output
231+
65232
7. You can check the repository setup for the Percona original release list in `/etc/apt/sources.list.d/percona-original-release.list`.
66233

67234
8. Install the server package with the `percona-release` command:
@@ -70,28 +237,145 @@ To install Percona Server for MySQL using APT, do the following steps:
70237
$ sudo apt install percona-server-server
71238
```
72239

240+
??? example "Expected output"
241+
242+
```{.text .no-copy}
243+
Reading package lists... Done
244+
Building dependency tree... Done
245+
Reading state information... Done
246+
The following NEW packages will be installed:
247+
percona-server-server
248+
The following packages will be upgraded:
249+
(none)
250+
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
251+
Need to get 45.2 MB of archives.
252+
After this operation, 234 MB of additional disk space will be used.
253+
Do you want to continue? [Y/n] y
254+
Get:1 https://repo.percona.com/apt jammy/main amd64 percona-server-server amd64 8.4.5-5.jammy [45.2 MB]
255+
Fetched 45.2 MB in 15s (3.01 MB/s)
256+
Selecting previously unselected package percona-server-server.
257+
(Reading database ... 123456 files and directories currently installed.)
258+
Preparing to unpack .../percona-server-server_8.4.5-5.jammy_amd64.deb ...
259+
Unpacking percona-server-server (8.4.5-5.jammy) ...
260+
Setting up percona-server-server (8.4.5-5.jammy) ...
261+
Processing triggers for man-db (2.10.2-1) ...
262+
Processing triggers for systemd (249.11-0ubuntu3.12) ...
263+
```
264+
265+
If this step fails:
266+
267+
* Check available packages: `apt search percona-server`
268+
269+
* Ensure the repository is properly configured
270+
271+
* Check for package conflicts with existing MySQL installations
272+
273+
* Review error messages for specific issues
274+
73275
See [Configuring Percona repositories with `percona-release`](https://docs.percona.com/percona-software-repositories/percona-release.html) for more information.
74276

75277
--8<--- "storage-engines.md"
76278

77-
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).
279+
## Next Steps
280+
281+
After successful installation, see [Post-installation](post-installation.md) for detailed steps to configure and secure your Percona Server for MySQL installation.
282+
283+
## Install Percona Toolkit UDFs (Optional)
284+
285+
Percona Server for MySQL includes user-defined functions (UDFs) from [Percona Toolkit](https://docs.percona.com/percona-toolkit/). These UDFs provide faster checksum calculations:
78286

79-
Once the installation completes, execute the following command to install these functions:
287+
* `fnv_64`: Fast hash function
80288

81-
```{.bash data-prompt="mysql>"}
82-
mysql> -e "INSTALL COMPONENT 'file://component_percona_udf'"
289+
* `fnv1a_64`: Alternative fast hash function
290+
291+
* `murmur_hash`: High-performance hash function
292+
293+
User-Defined Functions (UDFs) are custom functions you can add to MySQL to extend its capabilities. These particular UDFs are useful for data integrity checks and performance monitoring.
294+
295+
To install these functions after installation:
296+
297+
```{.sql data-prompt="mysql>"}
298+
mysql> INSTALL COMPONENT 'file://component_percona_udf';
83299
```
84300

85-
## Install the Percona Testing repository using APT
301+
??? example "Expected output"
302+
303+
```{.text .no-copy}
304+
Query OK, 0 rows affected (0.01 sec)
305+
```
306+
307+
You can now use these functions in your SQL queries. For example: `SELECT fnv_64('test_string');`
308+
309+
For detailed information about these functions, see [Percona Toolkit UDF functions](udf-percona-toolkit.md).
310+
311+
## Install the Percona testing repository (advanced users only)
86312

87-
Percona offers pre-release builds from the testing repository. To enable it, run
88-
percona-release with the `testing` argument. Run the following command as root or use the sudo command:
313+
Do not use testing repositories in production environments. Testing builds are pre-release versions that may contain bugs or incomplete features.
314+
315+
Percona offers pre-release builds from the testing repository for advanced users who want to:
316+
317+
* Test new features before official release
318+
319+
* Evaluate upcoming improvements
320+
321+
* Provide feedback on development versions
322+
323+
To enable the testing repository:
89324

90325
```{.bash data-prompt="$"}
91326
$ sudo percona-release enable {{pkg}} testing
92327
```
93328

94-
These builds should not be run in production. This build may not contain all of the features available in the final release. The features may change without notice.
329+
??? example "Expected output"
330+
331+
```{.text .no-copy}
332+
* Enabling Percona Server for MySQL 8.4 LTS testing repository
333+
* Running apt-get update...
334+
Hit:1 http://us.archive.ubuntu.com/ubuntu jammy InRelease
335+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
336+
Hit:3 http://us.archive.ubuntu.com/ubuntu jammy-backports InRelease
337+
Get:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [119 kB]
338+
Get:5 https://repo.percona.com/apt jammy InRelease [15.2 kB]
339+
Fetched 253 kB in 2s (126 kB/s)
340+
Reading package lists... Done
341+
Building dependency tree... Done
342+
Reading state information... Done
343+
All packages are up to date.
344+
```
345+
346+
Please be aware of the following limitations when using the testing repository:
347+
348+
* Features may change without notice
349+
350+
* Not all features from the final release may be included
351+
352+
* May contain experimental or incomplete functionality
353+
354+
* No production support for testing builds
355+
356+
To disable the testing repository and return to stable releases:
357+
358+
```{.bash data-prompt="$"}
359+
$ sudo percona-release disable testing
360+
$ sudo apt update
361+
```
362+
363+
??? example "Expected output"
364+
365+
```{.text .no-copy}
366+
* Disabling Percona testing repository
367+
* Running apt-get update...
368+
Hit:1 http://us.archive.ubuntu.com/ubuntu jammy InRelease
369+
Get:2 http://us.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
370+
Hit:3 http://us.archive.ubuntu.com/ubuntu jammy-backports InRelease
371+
Get:4 http://security.ubuntu.com/ubuntu jammy-security InRelease [119 kB]
372+
Get:5 https://repo.percona.com/apt jammy InRelease [15.2 kB]
373+
Fetched 253 kB in 2s (126 kB/s)
374+
Reading package lists... Done
375+
Building dependency tree... Done
376+
Reading state information... Done
377+
All packages are up to date.
378+
```
95379

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

0 commit comments

Comments
 (0)