Docker environment

The upgrade procedure depends on the version from which the upgrade is being performed and is only possible between two consecutive versions, such as from ASM 7.0.1 to ASM 7.1.0 or ASM 7.1.0 to ASM 7.2.0.

It is highly recommended to backup and restore your system before proceeding with an upgrade.

Important

Upgrading ASM will cause downtime for the application and consequently a temporary loss of service. As a result, the upgrade should be planned accordingly.

Backup and restore

It is recommended to backup your databases before each ASM version upgrade. In case that you encounter any issue during the upgrading you will be able to restore your previous version.

ASM 7.0.0 or 7.0.1

The following steps describe how to backup ASM 7.0.0 or ASM 7.0.1.

Backup

1. Stop all services except for the databases.

   $ docker stop docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

2. Enter the container.

   $ docker exec -it -u postgres docker_db_1 bash

3. Dump the databases inside the container.

   $ cd /tmp
   $ pg_dump asm > asm.sql
   $ pg_dump domain_manager > domain_manager.sql

4. Exit the container.

   $ exit

5. Copy the SQL files to the host.

   $ docker cp docker_db_1:/tmp/asm.sql .
   $ docker cp docker_db_1:/tmp/domain_manager.sql .

Restore

1. Stop all services except for the databases.

   $ docker stop docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

2. Copy the SQL files to the new database container.

   $ docker cp <path_to_file>/asm.sql docker_db_1:/
   $ docker cp <path_to_file>/domain_manager.sql docker_db_1:/

3. Enter the container.

   $ docker exec -it -u postgres docker_db_1 bash

4. Drop the databases, create them again and run the SQL files.

   $ psql template1 -c 'drop database asm'
   $ psql template1 -c 'drop database domain_manager'
   $ psql template1 -c 'create database asm'
   $ psql template1 -c 'create database domain_manager'
   $ psql asm < asm.sql
   $ psql domain_manager < domain_manager.sql

5. Exit the container.

   $ exit

6. Start all the service's containers again.

   $ docker start docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

ASM 7.1.0

The following steps describe how to backup ASM 7.1.0.

Backup

1. Stop all services except for the databases.

   $ docker stop docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

2. Enter the container.

   $ docker exec -it -u postgres docker_db_1 bash

3. Dump the databases inside the container.

   $ cd /tmp
   $ pg_dump asm > asm.sql
   $ pg_dump keycloak > keycloak.sql
   $ pg_dump domain_manager > domain_manager.sql

4. Exit the container.

   $ exit

5. Copy the SQL files to the host.

   $ docker cp docker_db_1:/tmp/asm.sql .
   $ docker cp docker_db_1:/tmp/keycloak.sql . 
   $ docker cp docker_db_1:/tmp/domain_manager.sql . 

Restore

1. Stop all services except for the databases.

   $ docker stop docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

2. Copy the SQL files to the new database container.

   $ docker cp <path_to_file>/asm.sql docker_db_1:/
   $ docker cp <path_to_file>/keycloak.sql docker_db_1:/
   $ docker cp <path_to_file>/domain_manager.sql docker_db_1:/

3. Enter the container.

   $ docker exec -it -u postgres docker_db_1 bash

4. Drop the databases, create them again and run the SQL files.

   $ psql template1 -c 'drop database asm'
   $ psql template1 -c 'drop database keycloak'
   $ psql template1 -c 'drop database domain_manager'
   $ psql template1 -c 'create database asm'
   $ psql template1 -c 'create database keycloak'
   $ psql template1 -c 'create database domain_manager'
   $ psql asm < asm.sql
   $ psql keycloak < keycloak.sql
   $ psql domain_manager < domain_manager.sql

5. Exit the container.

   $ exit

6. Start all the service's containers again.

   $ docker start docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

ASM 7.2.0+

The following steps describe how to backup ASM 7.2.0 or later version.

Backup

1. Stop all services except for the databases.

   $ docker stop docker-adm-1 docker-service-aggregator-1 docker-asm-1 docker-gateway-1 docker-keycloak-1 docker-pd-api-1 docker-pd-ui-1

2. Enter the container.

   $ docker exec -it -u postgres docker-db-1 bash

3. Dump the databases inside the container.

   $ cd /tmp
   $ pg_dump asm > asm.sql
   $ pg_dump keycloak > keycloak.sql
   $ pg_dump domain_manager > domain_manager.sql
   $ pg_dump pd > pd.sql

4. Exit the container.

   $ exit

5. Copy the SQL files to the host.

   $ docker cp docker-db-1:/tmp/asm.sql .
   $ docker cp docker-db-1:/tmp/keycloak.sql .
   $ docker cp docker-db-1:/tmp/domain_manager.sql .
   $ docker cp docker-db-1:/tmp/pd.sql .

Restore

1. Stop all services except for the databases.

   $ docker stop docker-adm-1 docker-service-aggregator-1 docker-asm-1 docker-gateway-1 docker-keycloak-1 docker-pd-api-1 docker-pd-ui-1

2. Copy the SQL files to the new database container.

   $ docker cp <path_to_file>/asm.sql docker-db-1:/
   $ docker cp <path_to_file>/keycloak.sql docker-db-1:/
   $ docker cp <path_to_file>/domain_manager.sql docker-db-1:/
   $ docker cp <path_to_file>/pd.sql docker-db-1:/

3. Enter the container.

   docker exec -it -u postgres docker-db-1 bash

4. Drop the databases, create them again and run the SQL files.

   $ psql template1 -c 'drop database asm'
   $ psql template1 -c 'drop database keycloak'
   $ psql template1 -c 'drop database domain_manager'
   $ psql template1 -c 'drop database pd'
   $ psql template1 -c 'create database asm'
   $ psql template1 -c 'create database keycloak'
   $ psql template1 -c 'create database domain_manager'
   $ psql template1 -c 'create database pd'
   $ psql asm < asm.sql
   $ psql keycloak < keycloak.sql
   $ psql domain_manager < domain_manager.sql
   $ psql pd < pd.sql

5. Exit the container.

   $ exit

6. Start all the service's containers again.

   $ docker start docker-adm-1 docker-service-aggregator-1 docker-asm-1 docker-gateway-1 docker-keycloak-1 docker-pd-api-1 docker-pd-ui-1

Upgrade procedure

ASM 6.2.x to 7.0.0

The upgrade from ASM 6.2.x version to ASM 7.0.0 is NOT supported.

ASM 7.0.0 to 7.0.1

The following steps describe how to upgrade from ASM 7.0.0 to ASM 7.0.1. The procedure is essentially about copying the database from the old environment to the new.

This method will only work for this particular upgrade because it cannot support future possible database migrations.

note

This upgrade procedure transfers the existing Keycloak users to the new database. This will hide the prompt for updating the password for the asm-admin user.

1. Enter the database container.

   $ docker exec -it -u postgres docker_db_1 bash

2. Dump the databases.

   $ cd /tmp
   $ pg_dump asm > asm.sql
   $ pg_dump domain_manager > domain_manager.sql

3. Exit the container.

   $ exit

4. Copy the SQL files to the host.

   $ docker cp docker_db_1:/tmp/asm.sql .
   $ docker cp docker_db_1:/tmp/domain_manager.sql . 

5. Navigate to the ASM 7.0.0 folder, stop ASM 7.0.0 and remove the containers.

   $ docker-compose down

6. Navigate to the ASM 7.0.1 folder and follow the instructions to run ASM.

7. Stop all the service's containers except for the database container when ASM 7.0.1 is up and running. Leave the database container up.

   $ docker stop docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

8. Copy the SQL files to the new database container.

   $ docker cp <path_to_file>/asm.sql docker_db_1:/
   $ docker cp <path_to_file>/domain_manager.sql docker_db_1:/

9. Enter the database container.

   $ docker exec -it -u postgres docker_db_1 bash

10. Drop the databases, create them again and run the SQL files.

    $ psql template1 -c 'drop database asm'
    $ psql template1 -c 'drop database domain_manager'
    
    $ psql template1 -c 'create database asm'
    $ psql template1 -c 'create database domain_manager'
    
    $ psql asm < asm.sql
    $ psql domain_manager < domain_manager.sql

11. Exit the container.

    $ exit

12. Start all the service's containers again.

    $ docker start docker_adm_1 docker_service-aggregator_1 docker_asm_1 docker_gateway_1 docker_keycloak_1

ASM 7.0.1 to 7.1.0

ASM 7.0.1 introduced state persistence using Docker Volumes.

The procedure is essentially about upgrading the database, and this method will only work for this particular upgrade.

note

The logs will not be migrated. The old logs will remain in the old 7.0.1 logs directory.

1. Navigate to the ASM 7.0.1 folder, stop ASM and remove all the containers.

   $ docker-compose down

2. Navigate to the ASM 7.1 folder and extract the ASM distribution .zip file to the folder from where you want to run ASM.

3. Navigate to the docker/ folder of the extracted distribution.

4. Open the file credentials.txt in a text editor.

5. Update the placeholder values for Access key ID and Secret access key with the values provided by Axiomatics. (These are the same values that were used in setting up AWS CLI.)

6. Save and close credentials.txt.

7. Copy a valid ASM license file to the docker/ folder. (This file is provided separately by Axiomatics.)

8. In the docker/ folder, start only the service's container for the database container.

   • Dashboard functionality:

     $ docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --detach --build db

   • No Dashboard functionality:

     $ docker-compose up --detach --build db

9. Enter the container.

   $ docker exec -it -u root docker_db_1 bash

10. Inside the container, run the following commands one by one:

    $ pg_dump -U "$POSTGRES_USER" -h localhost -d asm -T \"ISPN_DATA_jdbcRepository\" -T content_store -b > kc_data.sql
    $ psql -U "$POSTGRES_USER" -h localhost -c "CREATE DATABASE keycloak;"
    $ psql -U "$POSTGRES_USER" -h localhost -c "GRANT ALL PRIVILEGES ON DATABASE keycloak TO $POSTGRES_USER;"
    $ psql -q -U "$POSTGRES_USER" -h localhost -d keycloak -f kc_data.sql
    $ rm -f kc_data.sql

    $ pg_dump -U "$POSTGRES_USER" -h localhost -d asm -t \"ISPN_DATA_jdbcRepository\" -t content_store -b > asm_core_data.sql
    $ psql -U "$POSTGRES_USER" -h localhost -c "DROP DATABASE asm;"
    $ psql -U "$POSTGRES_USER" -h localhost -c "CREATE DATABASE asm;"
    $ psql -U "$POSTGRES_USER" -h localhost -c "GRANT ALL PRIVILEGES ON DATABASE asm TO    $POSTGRES_USER;"
    $ psql -q -U "$POSTGRES_USER" -h localhost -d asm -f asm_core_data.sql
    $ rm -f asm_core_data.sql

11. Exit the container.

    $ exit

12. Start all the service's containers again.

    • Dashboard functionality:

      $ docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --build

    • No Dashboard functionality:

      $ docker-compose up --build

ASM 7.1.0 to 7.2.0

The procedure is essentially about upgrading the relational database, and this method will only work for this particular upgrade.

note

The logs will not be migrated. The old logs will remain in the old 7.1.0 logs directory.

1. Navigate to the ASM 7.1.0 folder, stop ASM and remove all the containers.

   $ docker-compose down

2. Navigate to the ASM 7.2 folder and extract the ASM distribution ZIP file to the folder where you want to run ASM on.

3. Navigate to the docker/ folder of the extracted distribution.

4. Open the file credentials.txt in a text editor.

5. Update the placeholder values for Access key ID and Secret access key with the values provided by Axiomatics. (These are the same values that were used in setting up AWS CLI.)

6. Save and close credentials.txt.

7. Copy a valid ASM license file to the docker/ folder. (This file is provided separately by Axiomatics.)

8. In the docker/ folder, start only the service's container for the database container.

   • Dashboard functionality:

     $ docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --detach --build db

   • No Dashboard functionality:

     $ docker-compose up --detach --build db

9. Enter the container.

   $ docker exec -it -u root docker-db-1 bash

10. Inside the container, run the following commands one by one:

    $ psql -U "$POSTGRES_USER" -h localhost -c "CREATE DATABASE pd;"
    $ psql -U "$POSTGRES_USER" -h localhost -c "GRANT ALL PRIVILEGES ON DATABASE pd TO $POSTGRES_USER;"

11. Exit the container.

    $ exit

12. Start all the service's containers again.

    • Dashboard functionality:

      $ docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --build

    • No Dashboard functionality:

      $ docker-compose up --build