Downgrading from v5.0 to v4.5 or lower

If you want to downgrade from v5.0 to v4.5 or lower, you need to migrate down the MongoDB schema before switching to v4.5 and booting. Please follow the steps below.

TIP

Downgrading is availble for systems running on-premise or running with weseek/growi-docker-compose (opens new window). Please note that downgrading is not supported for other forms of system operations.

WARNING

Downgrading does not have the potential for data corruption, but there is a risk of data inconsistencies in the page's path. Please undertake it at your own risk as an administrator.

Procedure

Work Patterns with a Local Repository that is Meant for Production

  1. Stop the production server

    • Keep MongoDB running
  2. Perform following steps while keeping the v5.0.0 system available

    1. Start the bash process if you are using growi-docker-compose

      docker-compose run -it --rm app bash
      
    2. Run migrate-mongo down command in the packages/app directory

      • Run multiple times until MIGRATED DOWN: 20211227060705-revision-path-to-page-id-schema-migration.js appears in the terminal output.
      • Note: downgrading from v5.0.0 to v4.5.15 requires migrate-mongo down to be run 3 times.
      # 1st time (20220311011114-convert-page-delete-config)
      NODE_ENV=production node -r dotenv-flow/config node_modules/.bin/migrate-mongo down
      # 2nd time (20220131001218-convert-redirect-to-pages-to-page-redirect-documents)
      NODE_ENV=production node -r dotenv-flow/config node_modules/.bin/migrate-mongo down
      # 3rd time (20211227060705-revision-path-to-page-id-schema-migration)
      NODE_ENV=production node -r dotenv-flow/config node_modules/.bin/migrate-mongo down
      
  3. Switch the v4.5 system to the available state, build the client, then start the server

Patterns for Cloning Working Repository

  1. Stop the production server

    • Keep MongoDB running
  2. Clone the repository in an environment where you can access MongoDB in production

    git clone https://github.com/weseek/growi -b v5.0.0 --depth 1
    # Get dependent libraries
    yarn lerna bootstrap
    cd packages/app
    
  3. Create .env.local

    MIGRATIONS_DIR=src/migrations/
    # Please change according to your environment
    MONGO_URI="mongodb://${mongodbhost}:27017/growi"
    
  4. Execute migrate-mongo down command

    • Run multiple times until MIGRATED DOWN: 20211227060705-revision-path-to-page-id-schema-migration.js appears in the terminal output.
    • Note: downgrading from v5.0.0 to v4.5.15 requires migrate-mongo down to be run 3 times.
    # 1st time (20220311011114-convert-page-delete-config)
    yarn ts-node node_modules/.bin/migrate-mongo down
    # 2nd time (20220131001218-convert-redirect-to-pages-to-page-redirect-documents)
    yarn ts-node node_modules/.bin/migrate-mongo down
    # 3rd time (20211227060705-revision-path-to-page-id-schema-migration)
    yarn ts-node node_modules/.bin/migrate-mongo down
    
  5. Delete working repository

  6. Checkout v4.5 tags in production environment

  7. Build client, then start the server

Output Example

node ➜ /workspace/growi/packages/app (master) $ yarn ts-node node_modules/.bin/migrate-mongo down
yarn run v1.22.17
$ ts-node -r tsconfig-paths/register -r dotenv-flow/config --transpile-only node_modules/.bin/migrate-mongo down
{"name":"growi:migrate:convert-page-delete-config","hostname":"xxxxxxxxxxxx","pid":1111,"level":30,"msg":"Migration down has successfully applied","time":"2022-03-31T05:54:22.448Z","v":0}
MIGRATED DOWN: 20220311011114-convert-page-delete-config.js
Done in 1.71s.
node ➜ /workspace/growi/packages/app (master) $ yarn ts-node node_modules/.bin/migrate-mongo down
yarn run v1.22.17
$ ts-node -r tsconfig-paths/register -r dotenv-flow/config --transpile-only node_modules/.bin/migrate-mongo down
{"name":"growi:migrate:convert-redirect-to-pages-to-page-redirect-documents","hostname":"xxxxxxxxxxxx","pid":1111,"level":30,"msg":"Migration down has successfully applied","time":"2022-03-31T05:54:27.944Z","v":0}
MIGRATED DOWN: 20220131001218-convert-redirect-to-pages-to-page-redirect-documents.js
Done in 1.42s.
node ➜ /workspace/growi/packages/app (master) $ yarn ts-node node_modules/.bin/migrate-mongo down
yarn run v1.22.17
$ ts-node -r tsconfig-paths/register -r dotenv-flow/config --transpile-only node_modules/.bin/migrate-mongo down
{"name":"growi:migrate:revision-path-to-page-id-schema-migration","hostname":"xxxxxxxxxxxx","pid":1111,"level":30,"msg":"Migration down has successfully applied","time":"2022-03-31T05:54:31.169Z","v":0}
MIGRATED DOWN: 20211227060705-revision-path-to-page-id-schema-migration.js
Done in 1.99s.

Troubleshoot

ERROR: An env var MIGRATIONS_DIR must be set. Error: An env var MIGRATIONS_DIR must be set.

Create .env.local to temporarily set environment variables and setMIGRATIONS_DIR.

The pattern for working with a production local repository specifies MIGRATIONS_DIR=dist/migrations/ that can be run with Node.js.

The pattern for cloning the working repository specifies MIGRATIONS_DIR=src/migrations/ which can be executed with ts-node.