# Upgrade Polarity Server v4 to v5 > Ensure that the Server is running version 4.3.3 and Web version 4.4.5 before attempting the v5 upgrade, and that the PostgreSQL Server is running v13+ ## Confirm Operating System Check your operating system to ensure you are running the correct install commands ``` uname -a cat /etc/os-release ``` *** ## Database Backup **Check if backup exists** ``` cd /app/polarity-server-backups ``` Check for date of the backup, if it is from the day of the upgrade or the day before the upgrade you should be good to move forward with the upgrade. If not, or you just want to ensure you have the latest information follow the bext steps to create a backup. **Create DB backup** ``` sudo su - postgres -c '/app/polarity-server/data/backups/db-backup.sh' ``` > If you see cannot access errors related to the logs, or .git directory of integrations these errors can be safely ignored. The backup script does not copy any logs you may have from your integrations but the integrations themselves are copied. ## Convert TLS Key & Retain CA/Intermediate Certificate Chain The v5 Polarity Server requires that the SSL key be in PEM format using the PKCS8 container. Most customers will already be using these formats. Navigate to the key location ```bash cd /etc/pki/tls/private ``` Make a backup copy of your existing key ```bash cp server.key server.key.orig ``` Convert the key ```bash openssl rsa -in server.key.orig -outform pem > server.key ``` {% hint style="info" %} Ensure you have a copy of the CA and intermediate certificates required to validate the TLS certificate used on the v5 Polarity Server. If the v5 Polarity Server is unable to validate the entire chain for it’s TLS certificate, core integration functionality will not work properly {% endhint %} ## Edit DB Maximum Connection The DB maximum connection needs to be added or edited in the Polarity `.env` file. ``` sudo vi /app/polarity-server/.env ``` Check to see if there is the line `POLARITY_DB_CONNECTION_POOL_SIZE` if the line exists, edit it to be the following, if not please add the line to the .env file: ``` POLARITY_DB_CONNECTION_POOL_SIZE=50 ``` ## Install and Check Dependencies ### CentOS 7 / Amazon Linux 2 **JQ** ``` sudo yum install jq -y ``` **Docker** ``` sudo yum install docker -y ``` #### **Issue installing repos CentOS 7/AL2** If you are not able to install packages using `yum` on CentOS 7, there is a chance that the PostgreSQL repo needs to be updated. Run the following command: ``` yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm ``` **Docker Compose** ``` wget https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) mv docker-compose-$(uname -s)-$(uname -m) /usr/local/bin/docker-compose chmod -v +x /usr/local/bin/docker-compose ``` With CentOS 7/AL2 we will need to ensure that docker-compose is added to the path to ensure the commands will work in the future. ``` vi ~/.bashrc ``` Add the following line to the bottom of the file: ``` export PATH="$PATH:/usr/local/bin" ``` Then ensure the change takes effect immediately: ``` source ~/.bashrc ``` ### **CentOS Stream 8 / Rocky Linux 8 / RHEL 8** **JQ** ``` sudo dnf install jq -y ``` **Docker** For RHEL 8, `docker` is an alias for `podman`. This may cause issues, so we recommend installing `docker-ce` from the Docker repo directly. ``` sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo sudo dnf install docker-ce -y --allowerasing ``` **Docker Compose** ``` wget https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -O ./docker-compose mv ./docker-compose /usr/local/bin/ chmod -v +x /usr/local/bin/docker-compose ``` ## Enable and Check Docker Commands Enable Docker ``` systemctl enable docker ``` Check the Docker version commands to ensure Docker and Docker Compose is running ``` docker --version docker-compose --version ``` ## Download and Run Upgrade Script Navigate to the `/root` directory or a directory such as `/tmp` ``` cd /root ``` Download the upgrade script ``` sudo wget {{URL Provided by Polarity Rep}} ``` > Note the script is about 1.5GB so please ensure the directory has enough space for the script. Make the script executable ``` sudo chmod u+x upgrade_v4_to_v5-al2-offline-selfextract.sh ``` Run the script ``` ./upgrade_v4_to_v5-al2-offline-selfextract.sh ``` ## Script Prompts When executing the script, it will prompt for different commands. Below is a guide to the commands and what we here at Polarity recommend: > The script is very verbose and will prompt for every step the script is executing so admins can easily see if anything has failed. **First Prompt**: "`Press any Key to Continue`" - The initial prompt to let the admin know the script is running. Just press any key on the keyboard. **Second prompt**: "`Which directory do you wish to install Polarity V5 into?`" The default is `/app` which is the directory we recommend. You can proceed and just hit \[Enter] **Third Prompt**: "`Do you want to create a backup of the existing Polarity Platform v4 install directory (y/n)`" Here we recommend not creating a backup of the V4 install directory as there is a database backup already confirmed. We recommend `"n"` or `"no"` **Fourth Prompt**: "`Do you want to create a backup of the existing .env file (y/n) [yes]:`" This prompt is asking if you want to ensure a backup of the `.env` file is taken, which we recommend to ensure configurations are saved correctly. We recommend the default of `"y"` , `"yes"` or `[Enter]`. **Fifth Prompt**: "`Do you want to using the values from the existing .env file (y/n) [yes]:`" This prompt will utilize the values that were setup in the .env file originally. We recommend keeping these values and selecting the default of `"y"` , `"yes"` or `[Enter]` **Sixth Prompt:** "`Do you want to be prompted for each environment variable (y/n) [yes]:`" This prompt is to allow the admin to review and or change each of the values in the `.env` file. We recommend `"n"` or `"no"` **Integration Prompts:** The script will upgrade each of the integrations that are currently installed on the V4 server to ensure the integrations will work correctly. The script will check and try and match the names of the integrations to Polarity supported integrations. If there are any edited integrations or custom integrations present the script will prompt the admin to ask if they want to map the integration to a Polarity supported integration. We recommend mapping integrations if they have been renamed to something else, for example "Splunk Firewall". We recommend mapping it to our Splunk integration then changing the name after teh upgrade is complete to ensure the values are saved in the database. To map an integration to a Polarity supported one there are two ways to do so: 1. Name of the integration: Enter the name of the integration as it appears on the integrations github page, which can be found here: 2. Polarity Unique Identifier: Enter the Unique ID which can be found in the integration's `config/config.json` file on github: ; * The uniqe ID will look something like: "13aab2c0-a435-11ee-b809-03732f21d597" Seventh Prompt: "`Do you want to remove Polarity v4 packages (y/n) [no]:`" This prompt asks if admins want to remove the Version 4 packages from the server. We recommend to keep the packages on the server until the V5 server is up and running without issues. The packages can be removed at a later date. We recommend `"n"` or `"no"` Final Prompt: "`Do you want to remove Polarity v4 directories (y/n) [no]:`" This is the final prompt which asks if admins want to remove the Version 4 directories from the server. We recommend to keep the directories on the server until the V5 server is up and running without issues. The directories can be removed at a later date. We recommend `"n"` or `"no"` Script is complete when you see: > `All done. Good luck!` ## After Upgrade Steps When finishing the v4 to v5 upgrade process, Docker will be running 2 containers (polarity\_platform and polarity\_web). The PostgreSQL, Redis Integration Cache, and Redis Metrics Cache services will continue to be running on the host outside of docker. In the event your server reboots, it is important that the Redis services and PostgreSQL service start up after the Docker service starts. This is to ensure that the Docker network which is required for PostgreSQL, polarity-integration-cache, and polarity-metrics-cache is available for use. To do this, you will override the systemd unit file for each service using the `systemctl edit` command. Starting with the PostgreSQL service run the following command: ``` systemctl edit postgresql-13 ``` {% hint style="info" %} If you are running PostgreSQL 15, replace `postgresql-13` with `postgresql-15` {% endhint %} The above command will open the default text editor in which you should paste the following content: ``` [Unit] After=docker.service ``` {% hint style="info" %} The default text editor is most likely `vi` in which case you will need to press the `i` key to start "insert" mode before typing or pasting the above content. {% endhint %} If the editor is `vi` you can save the file by pressing `esc` and then `:wq` Next you will want to modify the integration cache service: ``` systemctl edit polarity-integration-cache ``` Add the some text as you did for the PostgreSQL service. Finally, repeat the process for the Metrics cache: ``` systemctl edit polarity-metrics-cache ``` After making the necessary unit file changes, you will need to restart the services for the changes to take effect: ``` systemctl daemon-reload systemctl restart postgresql-13 systemctl restart polarity-integration-cache systemctl restart polarity-metrics-cache ``` Finally, we recommend ensuring that the services are all enabled to start on boot with the following command: ``` systemctl enable postgresql-13 systemctl enable polarity-integration-cache systemctl enable polarity-metrics-cache ``` {% hint style="info" %} Again, if you are running PostgreSQL 15, replace `postgresql-13` with `postgresql-15` in the above commands. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.polarity.io/polarity-admin-guide-version-5/NgjzS0G79DnLnaNepozV/guides/upgrade-polarity-server-v4-to-v5.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.