From 1d17c343d5c2b5a9b72effa3d13d67a4f412c62e Mon Sep 17 00:00:00 2001 From: mich-elle-luna Date: Tue, 27 May 2025 14:21:48 -0700 Subject: [PATCH 1/2] Clarify custom installation requirements for custom storage paths (DOC-635) - Update install-on-linux.md to clearly explain when custom installation is needed - Add specific guidance about custom storage path requirements - Enhance customize-install-directories.md with troubleshooting section - Include specific error message and resolution steps - Add cross-references between installation and storage documentation - Address fragmented user experience by connecting related concepts Resolves DOC-635 --- .../install/customize-install-directories.md | 43 +++++++++++++++++++ .../install/install-on-linux.md | 36 ++++++++++++---- .../install/plan-deployment/file-locations.md | 4 ++ 3 files changed, 75 insertions(+), 8 deletions(-) diff --git a/content/operate/rs/installing-upgrading/install/customize-install-directories.md b/content/operate/rs/installing-upgrading/install/customize-install-directories.md index d49144035d..67207e68b8 100644 --- a/content/operate/rs/installing-upgrading/install/customize-install-directories.md +++ b/content/operate/rs/installing-upgrading/install/customize-install-directories.md @@ -14,6 +14,10 @@ When you install Redis Enterprise Software on Red Hat Enterprise Linux, you can The files are installed in the `redislabs` directory located in the path that you specify. +{{< note >}} +Custom installation is required if you plan to specify custom storage paths for persistent or ephemeral storage during cluster setup. If you install Redis Enterprise Software to default directories, you cannot specify custom storage paths during cluster creation. +{{< /note >}} + ## Considerations - When you install with custom directories, the installation does not run as an RPM file. @@ -76,6 +80,45 @@ To configure different mount points for data and log directories, use symbolic l ln -s /var/opt/redislabs/log ``` +## Custom storage paths + +When you install Redis Enterprise Software to custom directories, you can specify custom storage paths for persistent and ephemeral storage during [cluster setup]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}) or when [adding nodes]({{< relref "/operate/rs/clusters/add-node" >}}). + +### Prerequisites for custom storage paths + +Before specifying custom storage paths during cluster setup: + +1. Install Redis Enterprise Software to custom directories using the `--install-dir`, `--config-dir`, and `--var-dir` flags. + +2. Ensure proper permissions: The custom storage directories must have full permissions for the `redislabs` user and group (`redislabs:redislabs`). + +3. Verify mount points: Custom storage paths must be properly mounted and accessible. + +### Troubleshooting custom storage paths + +If you encounter the error "path entered is not mounted. Please correct" when specifying custom storage paths: + +1. Verify the installation method: Ensure Redis Enterprise Software was installed using custom directories. If you used the default installation (`sudo ./install.sh` without custom directory flags), you cannot specify custom storage paths. + +2. Check directory permissions: Ensure the `redislabs` user has full access to the specified directories: + ```sh + sudo chown -R redislabs:redislabs /path/to/custom/storage + sudo chmod -R 755 /path/to/custom/storage + ``` + +3. Verify mount points: Confirm the storage path is properly mounted: + ```sh + df -h /path/to/custom/storage + mount | grep /path/to/custom/storage + ``` + +4. Check directory existence: Ensure the directory exists and is accessible: + ```sh + ls -la /path/to/custom/storage + ``` + +For more information about storage requirements, see [Persistent and ephemeral node storage]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}). + ## Limitations Several Redis Enterprise Software installation reference files are installed to the directory `/etc/opt/redislabs/` even if you use custom installation directories. diff --git a/content/operate/rs/installing-upgrading/install/install-on-linux.md b/content/operate/rs/installing-upgrading/install/install-on-linux.md index 96020bb1fa..b136e68cb0 100644 --- a/content/operate/rs/installing-upgrading/install/install-on-linux.md +++ b/content/operate/rs/installing-upgrading/install/install-on-linux.md @@ -29,37 +29,57 @@ To install Redis Enterprise Software, use the command line: 1. _(Optional)_ Use the {{< download "GPG key file" "../GPG-KEY-redislabs-packages.gpg" >}} to confirm the authenticity of Ubuntu/Debian or RHEL RPM packages: - For Ubuntu: - 1. Import the key: + 1. Import the key: ```sh gpg --import - ``` - 2. Verify the package signature: - ```sh + ``` + 2. Verify the package signature: + ```sh dpkg-sig --verify ``` - For RHEL: - 1. Import the key: + 1. Import the key: ```sh rpm --import ``` - 2. Verify the package signature: + 2. Verify the package signature: ```sh rpm --checksig ``` -1. To start the installation process, run the installation script. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a list of command-line options you can add to the following command: +1. To start the installation process, run the installation script: + **For standard installation:** ```sh sudo ./install.sh ``` + **For custom installation directories:** + + If you need to specify custom storage paths for persistent or ephemeral storage during cluster setup, you must install Redis Enterprise Software to custom directories. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a complete list of command-line options. + + ```sh + sudo ./install.sh --install-dir --config-dir --var-dir + ``` + + For detailed information about custom installations, see [Customize installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}). + {{< note >}} -- The Redis Enterprise Software files are installed in the default [file locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}). +- The Redis Enterprise Software files are installed in the default [file locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}) unless you specify custom directories. - By default, Redis Enterprise Software runs on the OS as the `redislabs` user and `redislabs` group. If needed, you can [specify a different user and group]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) during the installation. - You must either be the root user or use `sudo` to run the installation script. {{< /note >}} + ### When to use custom installation directories + + You should use custom installation directories if you need to: + + - Specify custom storage paths for persistent or ephemeral storage during cluster setup + - Install Redis Enterprise Software in non-default locations for organizational or security requirements + - Avoid using root directories for the installation + - Meet specific compliance or infrastructure requirements + 1. Answer the [installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions.md" >}}) when shown to complete the installation process. {{< note >}} diff --git a/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md b/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md index 38392ec807..55226dd19f 100644 --- a/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md +++ b/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md @@ -41,3 +41,7 @@ You can change these file locations for: - [Ephemeral and persistence storage]({{< relref "/operate/rs/clusters/new-cluster-setup.md" >}}) during cluster setup - [Socket files]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) after cluster setup + +{{< note >}} +To specify custom storage paths for ephemeral and persistent storage during cluster setup, you must install Redis Enterprise Software using [custom installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}). If you use the default installation, you cannot specify custom storage paths and will receive a "path not mounted" error. +{{< /note >}} From cb229b607c748d0d36af411c70209a969e9bfcd5 Mon Sep 17 00:00:00 2001 From: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com> Date: Fri, 30 May 2025 10:53:27 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Rachel Elledge <86307637+rrelledge@users.noreply.github.com> --- .../install/customize-install-directories.md | 39 +++++++------------ .../install/install-on-linux.md | 15 ++----- .../install/plan-deployment/file-locations.md | 2 +- 3 files changed, 17 insertions(+), 39 deletions(-) diff --git a/content/operate/rs/installing-upgrading/install/customize-install-directories.md b/content/operate/rs/installing-upgrading/install/customize-install-directories.md index 67207e68b8..70121a90bc 100644 --- a/content/operate/rs/installing-upgrading/install/customize-install-directories.md +++ b/content/operate/rs/installing-upgrading/install/customize-install-directories.md @@ -14,10 +14,6 @@ When you install Redis Enterprise Software on Red Hat Enterprise Linux, you can The files are installed in the `redislabs` directory located in the path that you specify. -{{< note >}} -Custom installation is required if you plan to specify custom storage paths for persistent or ephemeral storage during cluster setup. If you install Redis Enterprise Software to default directories, you cannot specify custom storage paths during cluster creation. -{{< /note >}} - ## Considerations - When you install with custom directories, the installation does not run as an RPM file. @@ -80,41 +76,32 @@ To configure different mount points for data and log directories, use symbolic l ln -s /var/opt/redislabs/log ``` -## Custom storage paths +## Customize storage paths When you install Redis Enterprise Software to custom directories, you can specify custom storage paths for persistent and ephemeral storage during [cluster setup]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}) or when [adding nodes]({{< relref "/operate/rs/clusters/add-node" >}}). -### Prerequisites for custom storage paths - -Before specifying custom storage paths during cluster setup: - -1. Install Redis Enterprise Software to custom directories using the `--install-dir`, `--config-dir`, and `--var-dir` flags. - -2. Ensure proper permissions: The custom storage directories must have full permissions for the `redislabs` user and group (`redislabs:redislabs`). -3. Verify mount points: Custom storage paths must be properly mounted and accessible. +1. Specify the custom file location with the `--var-dir` option when you install Redis Enterprise Software: -### Troubleshooting custom storage paths - -If you encounter the error "path entered is not mounted. Please correct" when specifying custom storage paths: - -1. Verify the installation method: Ensure Redis Enterprise Software was installed using custom directories. If you used the default installation (`sudo ./install.sh` without custom directory flags), you cannot specify custom storage paths. + ```sh + sudo ./install.sh --var-dir + ``` -2. Check directory permissions: Ensure the `redislabs` user has full access to the specified directories: +2. Grant the `redislabs` user access to the custom directories: ```sh - sudo chown -R redislabs:redislabs /path/to/custom/storage - sudo chmod -R 755 /path/to/custom/storage + $ sudo chown -R redislabs:redislabs /path/to/custom/storage + $ sudo chmod -R 755 /path/to/custom/storage ``` -3. Verify mount points: Confirm the storage path is properly mounted: +3. Confirm the storage path is properly mounted: ```sh - df -h /path/to/custom/storage - mount | grep /path/to/custom/storage + $ df -h /path/to/custom/storage + $ mount | grep /path/to/custom/storage ``` -4. Check directory existence: Ensure the directory exists and is accessible: +4. Verify the directory exists and is accessible: ```sh - ls -la /path/to/custom/storage + ls -l /path/to/custom/storage ``` For more information about storage requirements, see [Persistent and ephemeral node storage]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}). diff --git a/content/operate/rs/installing-upgrading/install/install-on-linux.md b/content/operate/rs/installing-upgrading/install/install-on-linux.md index b136e68cb0..b2d2f1674f 100644 --- a/content/operate/rs/installing-upgrading/install/install-on-linux.md +++ b/content/operate/rs/installing-upgrading/install/install-on-linux.md @@ -48,16 +48,16 @@ To install Redis Enterprise Software, use the command line: rpm --checksig ``` -1. To start the installation process, run the installation script: +1. To start the installation process, run the installation script. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a complete list of command-line options. - **For standard installation:** + **For default installation:** ```sh sudo ./install.sh ``` **For custom installation directories:** - If you need to specify custom storage paths for persistent or ephemeral storage during cluster setup, you must install Redis Enterprise Software to custom directories. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a complete list of command-line options. + If you need to specify custom storage paths for persistent or ephemeral storage during cluster setup, you must install Redis Enterprise Software to custom directories. ```sh sudo ./install.sh --install-dir --config-dir --var-dir @@ -71,15 +71,6 @@ To install Redis Enterprise Software, use the command line: - You must either be the root user or use `sudo` to run the installation script. {{< /note >}} - ### When to use custom installation directories - - You should use custom installation directories if you need to: - - - Specify custom storage paths for persistent or ephemeral storage during cluster setup - - Install Redis Enterprise Software in non-default locations for organizational or security requirements - - Avoid using root directories for the installation - - Meet specific compliance or infrastructure requirements - 1. Answer the [installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions.md" >}}) when shown to complete the installation process. {{< note >}} diff --git a/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md b/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md index 55226dd19f..a336e7b9a0 100644 --- a/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md +++ b/content/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md @@ -43,5 +43,5 @@ You can change these file locations for: - [Socket files]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) after cluster setup {{< note >}} -To specify custom storage paths for ephemeral and persistent storage during cluster setup, you must install Redis Enterprise Software using [custom installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}). If you use the default installation, you cannot specify custom storage paths and will receive a "path not mounted" error. +To specify custom paths for ephemeral and persistent storage during cluster setup, you must install Redis Enterprise Software using [custom installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}). If you use the default installation, you cannot specify custom storage paths and will receive a "path not mounted" error. {{< /note >}}