# v4.0.6+ to v4.1.8 migration guide

The Strapi v4.0.6+ to v4.1.8 migration guide upgrades versions of v4.0.6 and above to v4.1.8. The minimum configuration for config/admin now includes the API token API_TOKEN_SALT. Strapi no longer populates default values for the admin JWT in config/admin. Initial values are generated and stored in the .env file during project creation. Strapi no longer passes secrets to non-development environments, requiring users to set the secrets purposefully. The migration to v4.1.8 consists of 4 steps:

  • Upgrading the application dependencies
  • Fixing the breaking changes
  • Setting secrets for non-development environments
  • Reinitializing the application

# Upgrading the application dependencies to 4.1.8

PREREQUISITES

Stop the server before starting the upgrade.

  1. Upgrade all of the Strapi packages in the package.json to 4.1.8:
// path: package.json

{
  // ...
  "dependencies": {
    "@strapi/strapi": "4.1.8",
    "@strapi/plugin-users-permissions": "4.1.8",
    "@strapi/plugin-i18n": "4.1.8",
    "better-sqlite3": "7.4.6"
    // ...
  }
}

  1. Save the edited package.json file.

  2. Run either yarn or npm install to install the new version.

💡 TIP

If the operation doesn't work, try removing your yarn.lock or package-lock.json. If that doesn't help, remove the node_modules folder as well and try again.

# Fixing the breaking changes

  1. Modify the config/admin file. Strapi, by default, creates the environmental variable API_TOKEN_SALT and populates a unique value, stored in /.env at project creation. In order to update config/admin:
  • add the apiToken object,
  • remove the comma and default value from the ADMIN_JWT_SECRET parenthetical.

//path: config/admin.js

module.exports = ({ env }) => ({
  auth: {
    secret: env('ADMIN_JWT_SECRET'),
  },
  apiToken: {
    salt: env('API_TOKEN_SALT'),
  },
});
  1. ConfigureJWT_SECRET. JWT_SECRET is used by the Users and Permissions plugin, and populated in /.env. The property should be stored in config/plugins.js (or config/plugins.ts for a TypeScript project). The plugins file is not created by default in a Strapi application. If the file does not exist, users should create the file and add the following code snippet.
//  path: config/plugins.js

module.exports = ({ env }) => ({
  // ...
  'users-permissions': {
    config: {
    jwtSecret: env('JWT_SECRET')
  },
  },
  // ...
});

# Setting secrets for non-development environments

Users are required to set secrets for each unique environment, such as a production environment deployment on a platform. Strapi no longer passes the following secrets to non-development environments:

  • APP_KEYS
  • JWT_SECRET
  • API_TOKEN_SALT
  • ADMIN_JWT_SECRET

There are multiple methods to generate secrets, for example running openssl rand -base64 32 in the terminal (Mac and Linux OS). Generating unique secrets for each environment is recommended for increased security.

✋ CAUTION

The Hosting Provider Guides are being updated to reflect these changes. Community contributions updating the hosting guides are encouraged.

# Reinitializing the application

Rebuild the administration panel and start the application: