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​
Stop the server before starting the upgrade.
- Upgrade all of the Strapi packages in the
package.json
to4.1.8
:
{
// ...
"dependencies": {
"@strapi/strapi": "4.1.8",
"@strapi/plugin-users-permissions": "4.1.8",
"@strapi/plugin-i18n": "4.1.8",
"better-sqlite3": "7.4.6"
// ...
}
}
-
Save the edited
package.json
file.
Fixing the breaking changes​
- Modify the
config/admin
file. Strapi, by default, creates the environmental variableAPI_TOKEN_SALT
and populates a unique value, stored in/.env
at project creation. In order to updateconfig/admin
:
- add the apiToken object,
- remove the comma and default value from the
ADMIN_JWT_SECRET
parenthetical.
module.exports = ({ env }) ({
auth: {
secret: env('ADMIN_JWT_SECRET'),
},
apiToken: {
salt: env('API_TOKEN_SALT'),
},
});
- Configure
JWT_SECRET
.JWT_SECRET
is used by the Users and Permissions plugin, and populated in/.env
. The property should be stored inconfig/plugins.js
(orconfig/plugins.ts
for a TypeScript project). Theplugins
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.
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.
The Hosting Provider Guides are being updated to reflect these changes. Community contributions updating the hosting guides are encouraged.