Migrating to another instance with an external Oracle database

You can migrate OpenPages from one instance to another with an external database.

Before you begin

Your source and target environments must have the same version of Cloud Pak for Data.
Your source and target environments must have the same version of OpenPages.
Your source and target environments must have the same version of Oracle.
The status of OpenPages is Completed in both the source and target environments.
Ensure that no long-running OpenPages processes, such as FastMap imports, are in progress.
Ensure that no database scripts are running in your source or target environments.

About this task

Do this task when the load on your source and target environments is light. For example, choose a time when few users are logged in.

Complete all backup steps within a short time frame to ensure that the database and the application are in sync. Similarly, do all restore steps within a short time frame.

Procedure

Backing up your source environment

In your source environment, log in to your Red Hat® OpenShift® cluster as an instance administrator:
```
oc login OpenShift_URL:port
```
Change to the project where OpenPages is installed:
```
oc project <Project>
```
Run the following commands. Note the secret that is returned by each command. You need this information later.
```
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.encryption-key-pw}"
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.keystore-pw}"
oc get secret -n <openpages_project> openpages-instance_name-platform-secret -o jsonpath="{.data.opsystem-pw}"
```
In addition, you can migrate the initial secrets for the default user accounts. Do this, for example, if you did not change the initial password of a user account and you want to migrate the initial secret to your new instance. To get the secret, run the following command for each secret that you want to migrate:
```
oc get secret -n <openpages_project> openpages-instance_name-initialpw-secret -o jsonpath="{.data.<user name>}"
```
Replace the following values:

Variable Replace with

<instance_name> The name of your OpenPages instance.

<openpages_project> The name of the project where OpenPages is installed.

<user name> A user account.
The encoded password of the account is displayed. Save the password.
Back up OpenPages in your source environment by running the following commands.
1. Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts -n <openpages_project>
```
  To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-opinst-sts
2. Log in to the application server pod and open a terminal.
```
oc exec -it openpages-<instance_name>-sts-0 -- /bin/bash
```
3. Back up the openpages-storage directory.
```
cd /opt/ibm/OpenPages/aurora/bin
./OPBackup.sh /opt/ibm/OpenPages/temp nosrvrst
```
  Important: Do not use the /openpages-shared/openpages-backup-restore directory for this command.
4. Back up the application configuration.
```
cd /opt/ibm/OpenPages/aurora/bin
./OPBackup.sh /openpages-shared/openpages-backup-restore app-cp4d nosrvrst
```

Variable	Replace with
`<instance_name>`	The name of your OpenPages instance.
`<openpages_project>`	The name of the project where OpenPages is installed.
`<user name>`	A user account.

Backing up the external OpenPages database

Back up the external OpenPages database by running the following commands.
1. Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts -n <openpages_project>
```
  To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-openpagesinstance-sts
2. Log in to the application server pod and open a terminal.
```
oc exec -it openpages-<instance_name>-sts-0 -- /bin/bash
```
3. Stop OpenPages Services.
```
server stop defaultServer
```
Go to the <OP_HOME>/aurora/bin directory.

Note: Oracle Data Pump Directory property DB_BACKUP_DIR= in /opt/ibm/OpenPages/aurora/bin/op-backup-restore.env file is set to DB_BACKUP_DIR=OP_DATAPUMP_DIRECTORY by default, replace it with the correct value if different in your installation.
Do a full database backup of the OpenPages schema by using OPBackup.
```
./OPBackup.sh /opt/ibm/OpenPages/temp dbonly
```
Note:
Make sure DB_ALIAS and ORACLE_SQLPLUS are set in /opt/ibm/OpenPages/aurora/bin/op-backup-restore.env before runningOPBackup.sh

The <backup_directory> is the full path to a directory on the database server. This directory is where the log files are saved. If the file path is not specified, the OPBackup command uses the location that is specified by the BACKUP_LOCATION parameter in the <OP_HOME>/aurora/bin/op-backup-restore.env file.
A dump file is created in the OP_DATAPUMP_DIRECTORY directory.
Examine the backup log and make note of the dump file names. The naming convention is openpage_.dmp.
Copy the .dmp file to the OP_DATAPUMP_DIRECTORY directory on the database server in your target environment.
1. Locate the OP_DATAPUMP_DIRECTORY directory on the target database server. To find the OP_DATAPUMP_DIRECTORY directory, run the following SQL as the system user:
```
select directory_name, directory_path from dba_directories where directory_name = upper ('OP_DATAPUMP_DIRECTORY');
```
2. Copy the dump file to the OP_DATAPUMP_DIRECTORY directory on the target database server. The dump file name is openpage_.dmp.
  
  Note: Make sure to copy the .dmp file with the time stamp that matches when you ran the OPBackup command.

Restoring in the target environment

In your target environment, log in to your Red Hat OpenShift cluster as an instance administrator:
```
oc login OpenShift_URL:port
```
Change to the project where OpenPages is installed:
```
oc project <Project>
```
Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts -n <openpages_project>
```
To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-openpagesinstance-sts
Copy the openpages-storage backup file to your target environment.
1. In your source environment, copy the backup file from step 4.c to the current working directory of your source environment.
```
oc cp -n ${INSTANCE_NAMESPACE} openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/opt/ibm/OpenPages/temp/<Backup_File_Name> <Backup_File_Name>
```
2. Copy the backup file to the /openpages-shared/openpages-backup-restore directory in your target environment.
```
oc cp -n ${INSTANCE_NAMESPACE} <Backup_File_Name> openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name>
```
  Make a note of the file name. You need this file in a later step. This file contains the backup of the openpages-storage directory.

Copy the application configuration backup file to your target environment.

Copy the backup file from step 4.d to the current working directory of your source environment.

oc cp -n ${INSTANCE_NAMESPACE} openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name> <Backup_File_Name>

Copy the backup file to the /openpages-shared/openpages-backup-restore directory in your target environment.

oc cp -n ${INSTANCE_NAMESPACE} <Backup_File_Name> openpages-${OPENPAGES_INSTANCE_NAME}-sts-0:/openpages-shared/openpages-backup-restore/<Backup_File_Name>

Restore the openpages-storage directory.
1. Log in to the application server pod and open a terminal.
```
oc exec -it openpages-<instance_name>-sts-0 -- /bin/bash
```
2. Go to the /opt/ibm/OpenPages/openpages-backup-restore directory.
3. Locate the op_backup_<timestamp>.zip file that you copied from your source environment in step 13.
4. Run the following commands:
```
cd /opt/ibm/OpenPages/aurora/bin
./OPRestore <backup-file-name> <path-to-backup-location> app-nodb
```
  For example, if the openpages-storage backup is in op_backup_2023_10_20_21_43_04.zip, the commands are:
```
./OPRestore.sh op_backup_2023_10_20_21_43_04  
/openpages-shared/openpages-backup-restore app-nodb
```
5. Remove the openpages-storage backup file from the /openpages-shared/openpages-backup-restore directory.
6. Verify that the backup file from step 14 is now the most recent backup file in the /openpages-shared/openpages-backup-restore directory.
Exit from application server pod.
Restart the application server pod.
1. Scale down to 0 replicas.
```
oc scale --replicas=0 sts/openpages-<instance_name>-sts -n <openpages_project>
```
  To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-instance_name-sts
2. Wait until all application server pods are deleted.
3. Scale to 1 replica.
```
oc scale --replicas=1 sts/openpages-<instance_name>-sts -n <openpages_project>
```
The application configuration is restored.
Restore the database.
1. Log in to the application server pod and open a terminal.
```
oc exec -it openpages-<instance_name>-sts-0 -- /bin/bash
```
2. Stop OpenPages application server.
```
server stop defaultServer
```
3. Log on to SQL*Plus as the OpenPages database user.
```
cd /opt/ibm/OpenPages/aurora/bin 
```
```
sqlplus <openpages_db_user>/<openpages_db_password>@<openpages_db_alias>
```
  For example:
```
sqlplus openpage/passw0rd@OPXSSL
```
4. Use the spool command to create a log file.
```
spool** <log_file directory>/<log_file name>
```
  Ensure that you have write permission on the <log_file directory>. For Example:
```
spool /tmp/AuroraDbDelete.log
```
5. Run the AuroraDbDelete.sql script.
```
@AuroraDbDelete.sql
```
6. Log out of SQL*Plus.
Set the NLS_LANG variable if it's missing from Environment.
For example,
```
export NLS_LANG=AMERICAN_AMERICA.AL32UTF8
```

Import the OpenPages database schema.

Note: The Oracle Data Pump command IMPDP is used because the IMP command is not supported.

For more information about Oracle Data Pump, see the IBM OpenPages Administrator's Guide.

Run the following command to import the OpenPages database:

impdp <op_db_user>/\"<op_db_password>\"@<SID> DIRECTORY=OP_DATAPUMP_DIRECTORY DUMPFILE=<openpages_dump_file> LOGFILE=openpages_import.log exclude=statistics

Parameters and their descriptions: Importing the OpenPages database schema

Parameter	Description
<op_db_user>	The user name for accessing the OpenPages database.
<op_db_password>	The password for accessing the OpenPages database.
<SID>	The Oracle System Identifier (for example, `OP`). If you are using a pluggable database, use the service name of the pluggable database, not the container database.
<openpages_dump_file>	The .dmp file name of the backed-up OpenPages database schema: openpage_`<timestamp>`.dmp. Important: Do not enter a path. Enter only the file name.
DIRECTORY	Important: Do not enter an explicit path when you specify the DIRECTORY parameter. Use `OP_DATAPUMP_DIRECTORY` only.

If the import fails, review the log files carefully. A failure at the beginning of the process might cause a number of cascading failures that are a symptom of the root issue.

Note: Make sure user has read/write permissions for dump file name openpage_.dmp before running the restore.

Restart the application server pod.
1. Scale down to 0 replicas.
```
oc scale --replicas=0 sts/openpages-<instance_name>-sts
```
  To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-instance_name-sts
2. Wait until all application server pods are deleted.
Restore the secrets into the target environment.
```
oc edit secrets -n <openpages_project> openpages-<instance_name>-platform-secret
```
1. Update the values for each secret based on the values in your source environment.
  For more information, see Secrets in the Kubernetes documentation.
2. If you want to restore the initial secrets for the default user accounts, run the following command:
```
 oc edit secrets -n <openpages_project> openpages-<instance_name>-initialpw-secret
```
  Do this step, for example, if you did not change the initial password of a default user account and you want to migrate the account's initial secret from your old instance to your new instance.

Scale up to the number of replicas you want to use for the application server by running the following command:

oc scale --replicas=<#_of_replicas> sts/openpages-<instance_name>-sts

Replace the following values:

Variable Replace with

Variable	Replace with
`<#_of_replicas>`	Specify the number of replicas. Can be 1 or more.
`<StatefulSet_name>`	Specify the name of the StatefulSet for the application. To find the name of the StatefulSet, run `oc get sts` and look for a name that starts with `openpages-`. For example, `openpages-opinst-sts`

<#_of_replicas>

Specify the number of replicas.

Can be 1 or more.

<StatefulSet_name>

Specify the name of the StatefulSet for the application.

To find the name of the StatefulSet, run oc get sts and look for a name that starts with openpages-.

For example, openpages-opinst-sts