diff --git a/docs/developer-docs/latest/developer-resources/content-api/integrations/gridsome.md b/docs/developer-docs/latest/developer-resources/content-api/integrations/gridsome.md index 2e6ff1da79..91181cf9ba 100644 --- a/docs/developer-docs/latest/developer-resources/content-api/integrations/gridsome.md +++ b/docs/developer-docs/latest/developer-resources/content-api/integrations/gridsome.md @@ -28,7 +28,7 @@ Gridsome is a [Static Site Generator](https://www.staticgen.com/) and will fetch yarn add @gridsome/source-strapi ``` -- Add the `@gridsome/source-strapi` to the plugins section in the `gridsome-config.js` file: +- Add the `@gridsome/source-strapi` to the plugins section in the `gridsome.config.js` file: ```js module.exports = { diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md index 8f722be645..e849aa6e98 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md @@ -244,11 +244,25 @@ module.exports = ({ env }) => ({ }) ``` -You will also need to set the environment variable in Heroku for the `MY_HEROKU_URL` and `APP_KEYS`. This will populate the variables with something like `https://your-app.herokuapp.com/` and `dsfhasbvvfwfcerterzer+n1w==,afjdsagfsauzuwzref6==,kjdbgjerhgh6wireg==,jkssdhgjaksdgkjbsdg==` respectively. +You will also need to set the environment variables in Heroku for the `MY_HEROKU_URL`, `APP_KEYS`, `API_TOKEN_SALT`, `ADMIN_JWT_SECRET`, and `JWT_SECRET`. This will populate the variables with something like `https://your-app.herokuapp.com/` and various random keys from the `.env` file locally. In some cases it is recommended to create new random secrets instead and there are various methods to do so. + +To copy existing secrets from your environment config locally use the following: ```bash heroku config:set MY_HEROKU_URL=$(heroku info -s | grep web_url | cut -d= -f2) heroku config:set APP_KEYS=$(cat .env | grep APP_KEYS | cut -d= -f2-) +heroku config:set API_TOKEN_SALT=$(cat .env | grep API_TOKEN_SALT | cut -d= -f2) +heroku config:set ADMIN_JWT_SECRET=$(cat .env | grep ADMIN_JWT_SECRET | cut -d= -f2) +heroku config:set JWT_SECRET=$(cat .env | grep -w JWT_SECRET | cut -d= -f2) +``` + +The following `openssl` commands will generate random new secrets (Mac and Linux only): + +```bash +heroku config:set APP_KEYS=$(openssl rand -base64 32) +heroku config:set API_TOKEN_SALT=$(openssl rand -base64 32) +heroku config:set ADMIN_JWT_SECRET=$(openssl rand -base64 32) +heroku config:set JWT_SECRET=$(openssl rand -base64 32) ``` diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/render.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/render.md index a8e3aa2f8a..2286375cb6 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/render.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/render.md @@ -6,8 +6,6 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/setup-deployment-guid # Render -!!!include(developer-docs/latest/setup-deployment-guides/deployment/snippets/deployment-guide-not-updated.md)!!! - This guide explains how to update an existing Strapi project so it can be deployed on [Render](https://render.com). With persistent disks and managed PostgreSQL databases, Render gives you multiple different ways to store your content. Render services come with fully managed SSL, so it's no longer necessary to set up a proxy server to secure your Strapi app. Since Render services are automatically restarted if they become unresponsive, you don't need to use a process manager like `pm2` either. @@ -53,7 +51,7 @@ services: sizeGB: 1 envVars: - key: NODE_VERSION - value: 12.18.4 + value: 12.22.0 - key: NODE_ENV value: production - key: DATABASE_FILENAME @@ -62,6 +60,10 @@ services: generateValue: true - key: ADMIN_JWT_SECRET generateValue: true + - key: APP_KEYS + generateValue: true + - key: API_TOKEN_SALT + generateValue: true ``` ::: @@ -79,7 +81,7 @@ services: healthCheckPath: /_health envVars: - key: NODE_VERSION - value: 12.18.4 + value: 12.22.0 - key: NODE_ENV value: production - key: CLOUDINARY_NAME @@ -96,6 +98,10 @@ services: generateValue: true - key: ADMIN_JWT_SECRET generateValue: true + - key: APP_KEYS + generateValue: true + - key: API_TOKEN_SALT + generateValue: true databases: - name: strapi @@ -121,7 +127,7 @@ services: sizeGB: 1 envVars: - key: NODE_VERSION - value: 12.18.4 + value: 12.22.0 - key: NODE_ENV value: production - key: DATABASE_URL @@ -132,6 +138,10 @@ services: generateValue: true - key: ADMIN_JWT_SECRET generateValue: true + - key: APP_KEYS + generateValue: true + - key: API_TOKEN_SALT + generateValue: true databases: - name: strapi diff --git a/docs/developer-docs/latest/update-migration-guides/migration-guides.md b/docs/developer-docs/latest/update-migration-guides/migration-guides.md index 62d436c1df..3676335cd7 100644 --- a/docs/developer-docs/latest/update-migration-guides/migration-guides.md +++ b/docs/developer-docs/latest/update-migration-guides/migration-guides.md @@ -16,6 +16,7 @@ Migrations are necessary when upgrades to Strapi include breaking changes. The m ## v4 migration guides - [Migration guide from 4.0.x to 4.0.6](migration-guides/v4/migration-guide-4.0.x-to4.0.6.md) +- [Migration guide from 4.0.6 to 4.1.8](migration-guides/v4/migration-guide-4.0.x-to-4.1.8.md) ## v3 to v4 migration guides diff --git a/docs/developer-docs/latest/update-migration-guides/migration-guides/v4/migration-guide-4.0.x-to-4.1.8.md b/docs/developer-docs/latest/update-migration-guides/migration-guides/v4/migration-guide-4.0.x-to-4.1.8.md new file mode 100644 index 0000000000..4de7911e72 --- /dev/null +++ b/docs/developer-docs/latest/update-migration-guides/migration-guides/v4/migration-guide-4.0.x-to-4.1.8.md @@ -0,0 +1,126 @@ +--- +title: Migrate from 4.1.7 to 4.1.8 - Strapi Developer Docs +description: Learn how you can migrate your Strapi application from 4.1.7 to 4.1.8. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/update-migration-guides/migration-guides/v4/migration-guide-4.0.x-to-4.1.8.html +--- + +# v4.0.x to v4.1.8 migration guide + +The Strapi v4.0.x to v4.1.8 migration guide upgrades versions of v4.0.6 through v4.1.7 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: + +- adding the API token to `config/admin`, +- removing the default `ADMIN_JWT_SECRET` (recommended for improved security), +- configuring `JWT_SECRET` in `config/plugins` (recommended), +- setting secrets for non-development environments. + +## Modifying 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. + + + + + +```jsx + +//path: config/admin.js + +module.exports = ({ env }) => ({ + auth: { + secret: env('ADMIN_JWT_SECRET'), + }, + apiToken: { + salt: env('API_TOKEN_SALT'), + }, +}); + +``` + + + + + +```jsx +//path: config/admin.ts + +export default ({ env }) => ({ + auth: { + secret: env('ADMIN_JWT_SECRET'), + }, + apiToken: { + salt: env('API_TOKEN_SALT'), + }, +}); + + +``` + + + + + +## Configuring `JWT_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 follow code snippet. + + + + + +```jsx +// path: config/plugins.js + +module.exports = ({ env }) => ({ + // ... + 'users-permissions': { + config: { + jwtSecret: env('JWT_SECRET') + }, + }, + // ... +}); + +``` + + + + + +```jsx +// path: config/plugins.ts + +export default ({ 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](/developer-docs/latest/setup-deployment-guides/deployment.html#hosting-provider-guides.md) are being updated to reflect these changes. Community contributions updating the hosting guides are encouraged. + +:::