diff --git a/docs/apt-download-deb.md b/docs/apt-download-deb.md index ab0db88ada3..0e90d7c7a19 100644 --- a/docs/apt-download-deb.md +++ b/docs/apt-download-deb.md @@ -1,39 +1,66 @@ -# Install Percona Server for MySQL {{vers}} using downloaded DEB packages +# Install Percona Server for MySQL 8.4 using DEB packages -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. +Percona distributes DEB packages in tar bundles that contain multiple related packages. Two bundle types are available: -The following example downloads Percona Server for MySQL {{release}} release packages for Ubuntu 22.04: +* Full bundle: Contains all Percona Server packages including server, client, test packages, debug symbols, and source files + +* Minimal bundle: Contains only the essential server and client packages needed for basic operation + +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. + +## When to use this installation method + +Skills needed: Basic system administration, command line familiarity + +Advantages: + +* Provides precise version control over installed packages + +* Works in offline environments without internet access + +* Allows installation before packages appear in standard repositories + +* Enables administrators to validate packages before deployment + +Disadvantages: + +* Requires manual download and extraction steps + +* Does not receive automatic updates through the package manager + +* Users must manually track new releases and security updates + +* Takes more time than repository-based installation + +Download the bundle from Percona Product Downloads. Review the Instructions for the Percona Product Download if you need assistance. + +This example downloads Percona Server for MySQL {{release}} release packages for Ubuntu 22.04: ```{.bash data-prompt="$"} -$ 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 +$ 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 ``` -Unpack the download to get the packages: +Extract the bundle to access the individual packages: ```{.bash data-prompt="$"} -$ tar xvf Percona-Server-8.4.0-1-r71449379-buster-x86_64-bundle.tar +$ tar xvf Percona-Server-{{release}}-[revision hash]-jammy-x86_64-bundle.tar ``` -??? example "Expected output" - - ```text - libperconaserverclient21_{{release}}-1.buster_amd64.deb - libperconaserverclient21-dev_{{release}}-1.buster_amd64.deb - percona-mysql-router_{{release}}-1.buster_amd64.deb - percona-server-client_{{release}}-1.buster_amd64.deb - percona-server-common_{{release}}-1.buster_amd64.deb - percona-server-dbg_{{release}}-1.buster_amd64.deb - percona-server-rocksdb_{{release}}-1.buster_amd64.deb - percona-server-server_{{release}}-1.buster_amd64.deb - percona-server-source_{{release}}-1.buster_amd64.deb - percona-server-test_{{release}}-1.buster_amd64.deb + +??? example "Expected output for a full tar extraction" + + ```{.text .no-copy} + percona-server-server_{{release}}-1.jammy_amd64.deb + percona-server-client_{{release}}-1.jammy_amd64.deb + percona-server-common_{{release}}-1.jammy_amd64.deb + percona-server-dbg_{{release}}-1.jammy_amd64.deb + percona-server-source_{{release}}-1.jammy_amd64.deb + percona-server-test_{{release}}-1.jammy_amd64.deb ``` -Install Percona Server for MySQL using `dpkg`. Run this command as root or use the sudo command: +Install Percona Server for MySQL using the system package manager. Run this command as root or use sudo: ```{.bash data-prompt="$"} -$ sudo dpkg -i *.deb +$ sudo apt install ./*.deb ``` -!!! warning - - 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`. +The package manager resolves dependencies automatically and installs all required components from the extracted files. \ No newline at end of file diff --git a/docs/apt-pinning.md b/docs/apt-pinning.md index 7f20c881aed..04885397c08 100644 --- a/docs/apt-pinning.md +++ b/docs/apt-pinning.md @@ -1,15 +1,44 @@ # Apt pinning the Percona Server for MySQL {{vers}} packages -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. +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. -The pinning takes place in the `preference` file. To pin a package, set the `Pin-Priority` to higher numbers. - -Make a new file `/etc/apt/preferences.d/00percona.pref`. For example, add the following to the `preference` file: +To pin the Percona Server for MySQL 8.4 packages, follow these steps: +{.power-number} -```text -Package: -Pin: release o=Percona Development Team -Pin-Priority: 1001 -``` +1. Create a preferences file in `/etc/apt/preferences.d/` named `00percona.pref`: -For more information about the pinning, you can check the official [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences). + ```{.bash data-prompt="$"} + $ sudo nano /etc/apt/preferences.d/00percona.pref + ``` + +2. Add the pinning configuration content to the file: + + ```ini + Package: percona-server-server + Pin: release o=Percona Development Team,a=stable + Pin-Priority: 1001 + ``` + + * The `Package` field specifies the exact name of the package. + * The `Pin` field identifies the origin of the package, which is the Percona repository. + * The `Pin-Priority` field sets the priority level. A value above 1000 ensures this version is preferred over others. + + Save and close the file. + +3. Update package lists to refresh your package sources: + + ```{.bash data-prompt="$"} + $ sudo apt update + ``` + +4. Install Percona Server for MySQL 8.4 using the following command: + + ```{.bash data-prompt="$"} + $ sudo apt install percona-server-server + ``` + + Your system prioritizes the version from the Percona repository according to your pinning settings. + +## Learn more + +For additional details, visit the [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences). diff --git a/docs/apt-repo.md b/docs/apt-repo.md index d4f8aa73b48..92fd693bfa4 100644 --- a/docs/apt-repo.md +++ b/docs/apt-repo.md @@ -1,64 +1,59 @@ -# Use an APT repository to install Percona Server for MySQL {{vers}} +# Install Percona Server for MySQL {{vers}} Using APT on Debian/Ubuntu -Ready-to-use packages are available from the Percona Server for MySQL software -repositories and the [Percona downloads] page. +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. -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). +If you need help with installation or configuration, [Percona Support](https://www.percona.com/services/support) is available to assist you. + +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). + +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]. -We gather [Telemetry data] in the Percona packages and Docker images. ---8<--- "get-help-snip.md" ## ARM support -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. +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. + ## Install Percona Server for MySQL using APT To install Percona Server for MySQL using APT, do the following steps: {.power-number} -1. Update the package repositories: +1. Update the package index and install `curl`: ```{.bash data-prompt="$"} - $ sudo apt update + $ sudo apt update && sudo apt install curl ``` -2. Install the `curl` download utility if needed: - - ```{.bash data-prompt="$"} - $ sudo apt install curl - ``` - -3. Download the `percona-release` repository package: +2. Download the `percona-release` repository package: ```{.bash data-prompt="$"} $ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb ``` -4. Install the downloaded package with `apt` as root or with sudo: +3. Install the package with `apt` as root or with sudo: ```{.bash data-prompt="$"} $ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb ``` - -5. Refresh the local cache to update the package information: +4. Refresh the package index: ```{.bash data-prompt="$"} $ sudo apt update ``` -6. Use `percona-release` to set up the repository for the Percona Server for MySQL {{vers}} version: +5. Enable the Percona Server for MySQL {{vers}} repository: ```{.bash data-prompt="$"} $ sudo percona-release enable-only {{pkg}} release $ sudo percona-release enable tools release ``` -7. You can check the repository setup for the Percona original release list in `/etc/apt/sources.list.d/percona-original-release.list`. +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```. -8. Install the server package with the `percona-release` command: +8. Install the server: ```{.bash data-prompt="$"} $ sudo apt install percona-server-server @@ -68,7 +63,7 @@ See [Configuring Percona repositories with `percona-release`](https://docs.perco --8<--- "storage-engines.md" -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). +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). Once the installation completes, execute the following command to install these functions: @@ -89,4 +84,4 @@ These builds should not be run in production. This build may not contain all of [Percona downloads]: https://www.percona.com/downloads/Percona-Server-{{vers}}/ -[Telemetry data]: telemetry.md \ No newline at end of file +[Telemetry in Percona Server for MySQL]: telemetry.md \ No newline at end of file diff --git a/docs/build-apt-packages.md b/docs/build-apt-packages.md index 8cf5cb32008..a3e663b6a30 100644 --- a/docs/build-apt-packages.md +++ b/docs/build-apt-packages.md @@ -1,28 +1,61 @@ -# Build APT packages +# Build DEB packages from source -If you wish to build your own Debian/Ubuntu (dpkg) packages of Percona Server for MySQL, -you first need to start with a source tarball, either from the Percona -website or by generating your own by following the instructions above ([Installing Percona Server for MySQL from the Git Source Tree](source-tarball.md)). +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. + +## When to build from source + +Advantages: + + Enables custom compilation flags and configuration options + +* Allows integration of custom patches or modifications + +* Creates packages tailored for specific hardware or requirements + +* Provides control over included features and dependencies + +Disadvantages: + +* Requires significant build time and system resources + +* Demands expertise in Debian packaging and build tools + +* Creates maintenance overhead for updates and security patches + +* May introduce stability risks from custom modifications + +## Prerequisites + +Skills needed: Software development, packaging knowledge, build tools + +Install the required build tools and dependencies: + +```{.bash data-prompt="$"} +$ sudo apt install build-essential devscripts debhelper sbuild +$ sudo apt build-dep percona-server-server +``` + +## Build process + +Start with a source tarball from the Percona website or generate your own following the Git source tree installation instructions. Extract the source tarball: ```{.bash data-prompt="$"} -$ tar xfz Percona-Server-{{release}}-Linux.x86_64.ssl102.tar.gz +$ tar xfz Percona-Server-{{release}}-Linux.x86_64.tar.gz $ cd Percona-Server-{{release}} ``` -Copy the Debian packaging in the directory that Debian expects it to be in: +Copy the Debian packaging files to the expected directory structure: ```{.bash data-prompt="$"} $ cp -ap build-ps/debian debian ``` - -Update the changelog for your distribution (here we update for the unstable -distribution - sid), setting the version number appropriately. The trailing one -in the version number is the revision of the Debian packaging. + +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: ```{.bash data-prompt="$"} -$ dch -D unstable --force-distribution -v "8.0.13-3-1" "Update to 8.0.13-3" +$ dch -D unstable --force-distribution -v "{{release}}-1" "Update to {{release}}" ``` Build the Debian source package: @@ -31,15 +64,16 @@ Build the Debian source package: $ dpkg-buildpackage -S ``` -Use sbuild to build the binary package in a chroot: +Use sbuild to create the binary package in a clean chroot environment: ```{.bash data-prompt="$"} -$ sbuild -d sid percona-server-{{vers}}_{{release}}.dsc +$ sbuild -d sid percona-server-8.4_{{release}}.dsc ``` -You can give different distribution options to `dch` and `sbuild` to build binary -packages for all Debian and Ubuntu releases. - !!! note - [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. + 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. + +## Distribution compatibility + +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`). \ No newline at end of file diff --git a/docs/installation-methods.md b/docs/installation-methods.md new file mode 100644 index 00000000000..3c54fdc8660 --- /dev/null +++ b/docs/installation-methods.md @@ -0,0 +1,123 @@ +# Installation methods + +This guide outlines the primary methods for installing Percona Server for MySQL, comparing their advantages and use cases to help you choose the right approach for your environment. + +## APT/YUM or DNF (package managers) + +* [Install with APT](apt-repo.md) + +* [Install with YUM/DNF](yum-repo.md) + +This is the standard and recommended method for most users on a supported Linux distribution. This method uses the Percona release tool with a package manager to handle the installation from a pre-configured repository. The package manager automatically resolves and installs all required dependencies. + + * Common Use Cases: + + * Production servers where stability and easy maintenance are critical. + + * Automated deployments and provisioning. + + * Users who want a simple, clean, and reliable installation process. + + * Pros: + + * Dependency Management: All dependencies are handled automatically. + + * Easy Updates: Upgrading to new versions or applying security patches is a single command. + + * Reliability: Packages are tested for the specific operating system and architecture. + + * Clean Uninstallation: Removes all files without leaving orphaned data. + + * Cons: + + * Version Availability: You are limited to the versions available in the repository. + +### Manual Package Installation (.deb/.rpm) + +* [Download and install with APT packages](apt-download-deb.md) + +* [Download and install with RPM packages](yum-download-rpm.md) + + + +This method is a hybrid approach, offering more control than a repository but still leveraging the package manager for the final installation. It's used when you have the package file but don't want to use an online repository. You download a specific package file (for example, a .deb or .rpm) directly from the Percona website. You then install the package file using a local command-line tool like apt or dnf, which processes the file. + + * Common Use Cases: + + * Installing on a system with no internet access to the public repositories. + + * Deploying a specific point release for testing or compatibility. + + * Troubleshooting when repository access is an issue. + + * Pros: + + * Precise Version Control: You get exactly the version of the package you download. + + * No Repository Required: The server doesn't need to access an online repository. + + * Uses Package Manager: The package file can still manage dependencies and is easy to remove. + + * Cons: + + * Manual Dependencies: You must manually download and install any required dependency packages first. + + * Manual Updates: You have to manually download and install new versions. + + * No Automatic Security Patches: You are responsible for monitoring and installing security updates. + +### Tar Files + +* [Download and install .tar file](binary-tarball-install.md) + +This method gives you more control than a package manager but still provides a pre-compiled binary that does not require compilation. You download a compressed tarball (.tar.gz) containing the pre-compiled binaries directly from the Percona website. You then extract the files to a directory of your choice and manually configure the environment. + + * Common Use Cases: + + * Installing on unsupported Linux distributions or non-standard environments. + + * Testing a specific version that isn't yet available in a repository. + + * Installing for Local development. + + * Pros: + + * Flexibility: Provides the latest versions directly from the source. + + * Portability: The installation is often self-contained within a directory. + + * Control: You decide exactly where to install the files. + + * Cons: + + * Manual Dependencies: You are responsible for manually installing any required libraries. + + * Manual Maintenance: Updating to a new version requires you to download, extract, and re-link the new files. + +## Compile from source + +* [Compile from source](compile-percona-server.md) + +This is the most hands-on method, offering the highest level of customization and control over the final installation. You download the raw source code, use a C++ compiler and other tools to build the software on your local machine, and then install the resulting binaries. This method requires a comprehensive build environment. + + * Common Use Cases: + + * Building for an unsupported architecture. + + * Debugging or modifying the server's code. + + * Optimizing the server for a specific hardware configuration. + + * Pros: + + * Ultimate Control: You can customize every aspect of the build, including which features to enable or disable. + + * Platform Flexibility: Can be compiled and run on virtually any system that has the required build tools. + + * Cons: + + * Complex Dependencies: Requires you to manually manage all build-time dependencies, which can be extensive. + + * Time-Consuming: The compilation process can take a significant amount of time. + + * Difficult Maintenance: Updating or uninstalling requires manual, complex steps. \ No newline at end of file diff --git a/docs/manual-package-install.md b/docs/manual-package-install.md new file mode 100644 index 00000000000..9dd105bdae1 --- /dev/null +++ b/docs/manual-package-install.md @@ -0,0 +1,117 @@ +# Install Percona Server for MySQL from a Local Package File + +You can install Percona Server for MySQL without using an online repository. This method uses a package file that you download directly from the Percona website and then install locally with your system’s package manager. + +## Why install from a local package file + +Installing from a local file provides control over the exact package version. This method works well in environments without internet access or when administrators prefer to manage package distribution internally. + +This method is commonly used when you need: + +* A specific version that is not available in the standard repositories + +* Installation in offline/air-gapped environments + +* Direct control over package sources for security or compliance reasons + +* Installation before the package is available through normal repository channels + +## Steps to install + +1. Download the package file + + Go to [Percona Software Downloads](https://www.percona.com/downloads/). Select the desired version of Percona Server for MySQL. Choose the package format that matches your operating system: + + * `.deb` for Debian-based distributions, such as Ubuntu + + * `.rpm` for Red Hat-based distributions, such as CentOS, AlmaLinux, or Rocky Linux + + Save the file to a directory on your local system. + + An example for a Debian 12 ARM64 system: + + ```{.bash data-prompt="$"} + $ wget https://downloads.percona.com/downloads/Percona-Server-8.4/Percona-Server-{{release}}/binary/debian/bookworm/aarch64/percona-server-server_{{release}}-1.bookworm_arm64.deb + ``` + + An example for Red Hat Enterprise Linux (RHEL) ARM64 system: + + ```{.bash data-prompt="$"} + $ wget https://downloads.percona.com/downloads/Percona-Server-8.4/Percona-Server-{{release}}/binary/redhat/9/aarch64/percona-server-server-{{release}}.1.el9.aarch64.rpm + ``` + +2. Install the package file + + Use your system’s package manager to process the local file. + + For Debian-based systems: + + ```{.bash data-prompt="$"} + $ sudo apt install ./percona-server-server_{{release}}-1.bookworm_aarch64.deb + ``` + + For Red Hat Enterprise Linux-based systems: + + ```{.bash data-prompt="$"} + $ sudo dnf install percona-server-server-{{release}}-1.el9.aarch64.rpm + ``` + + The package manager verifies dependencies and installs the software from the local file. + +## Troubleshooting missing dependencies + +If the package manager reports missing dependencies: + +* Review the error message to identify the missing packages. + +* Download the missing packages from a trusted source. + +* Install the missing packages locally using the same package manager. + +An example for Debian 12 system: + +```{.bash data-prompt="$"} +$ sudo apt install ./libexample_1.2.3-1_aarch64.deb +``` + +An example for RHEL 9 system: + +```{.bash data-prompt="$"} +$ sudo dnf install libexample-1.2.3-1.el9.aarch64.rpm +``` + +Repeat the installation of Percona Server for MySQL after resolving all dependencies. + +## Verify the installation + +After installing, verify that Percona Server for MySQL is installed and running. + +Check the installed version: + +```{.bash data-prompt="$"} +$ mysql --version +``` + +Check the service status: + +```{.bash data-prompt="$"} +$ sudo systemctl status mysql +``` + +If the service is running, the output includes ```active (running)```. + +### If the service is not running + +If systemctl shows that the MySQL service is inactive or failed: + +* Review recent log messages for errors + +* Check the MySQL error log, usually located in `/var/log/mysql/` or `/var/log/mysqld.log`. + +* Start the service manually: + + ```{.bash data-prompt="$"} + $ sudo systemctl start mysql + ``` + +If the service still does not start, investigate configuration issues, missing dependencies, or port conflicts. \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 1769735f23c..ec7bb99241c 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -246,26 +246,27 @@ nav: - Install: - Install Percona Server for MySQL from repositories: installation.md - Before you start: + - installation-methods.md - download-instructions.md - - Use APT: - - Use APT repositories: apt-repo.md + - APT: + - Install using APT repositories: apt-repo.md - Files in DEB package: apt-files.md - - build-apt-packages.md - - Downloaded DEB packages: apt-download-deb.md - - Apt pinning: apt-pinning.md - - Run Percona Server for MySQL: apt-run.md + - apt-download-deb.md + - apt-pinning.md - Uninstall: apt-uninstall-server.md - - Use YUM: - - Use RPM repositories: yum-repo.md + - YUM: + - Install using RPM repositories: yum-repo.md - Files in RPM package: yum-files.md - - Downloaded RPM packages: yum-download-rpm.md + - Download RPM packages: yum-download-rpm.md - Run Percona Server for MySQL: yum-run.md - Uninstall: yum-uninstall.md - - Use binary tarballs: + - Manual package installation: manual-package-install.md + - Binary tarballs: - Install with binary tarballs: binary-tarball-install.md - Binary tarballs available: binary-tarball-names.md - - Compile from source: + - Build from source: - source-tarball.md + - build-apt-packages.md - compile-percona-server.md - Docker: - Install using Docker: docker.md @@ -279,6 +280,7 @@ nav: - upgrade-standalone-packages.md - downgrade.md - Post-Installation: + - Run Percona Server for MySQL: apt-run.md - binlogging-replication-improvements.md - post-installation.md - AppArmor: