From fc6245b2d56cc8928610c4d695493760be7c2a7b Mon Sep 17 00:00:00 2001 From: Alexandre Bodin Date: Mon, 25 May 2020 14:23:38 +0200 Subject: [PATCH 1/4] Migration guide for stable Signed-off-by: Alexandre Bodin --- docs/3.0.0-beta.x/migration-guide/README.md | 5 +- .../migration-guide-beta.20-to-3.0.0.md | 245 ++++++++++++++++++ docs/3.0.0-beta.x/plugins/upload.md | 44 ++-- packages/strapi/lib/core/load-middlewares.js | 22 +- 4 files changed, 273 insertions(+), 43 deletions(-) create mode 100644 docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md diff --git a/docs/3.0.0-beta.x/migration-guide/README.md b/docs/3.0.0-beta.x/migration-guide/README.md index 0334080496..ad4a95fce0 100644 --- a/docs/3.0.0-beta.x/migration-guide/README.md +++ b/docs/3.0.0-beta.x/migration-guide/README.md @@ -2,9 +2,9 @@ Please also refer to the following [documentation](../guides/update-version.md) for a better understanding of how to update your project -## Migrating from Alpha ? +## Migrating from Beta ? -Read the [Migration guide from alpha.26 to beta](migration-guide-alpha.26-to-beta.md) first then read the [Beta migration guides](#beta-guides) +Read the [Migration guide from beta.20+ to stable](migration-guide-beta.20-to-3.0.0.md). ## Beta guides @@ -14,6 +14,7 @@ Read the [Migration guide from alpha.26 to beta](migration-guide-alpha.26-to-bet - [Migration guide from beta.18 to beta.19](migration-guide-beta.18-to-beta.19.md) - [Migration guide from beta.19+ to beta.19.4](migration-guide-beta.19-to-beta.19.4.md) - [Migration guide from beta.19.4+ to beta.20](migration-guide-beta.19-to-beta.20.md) +- [Migration guide from beta.20+ to stable](migration-guide-beta.20-to-3.0.0.md) ## Alpha guides diff --git a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md new file mode 100644 index 0000000000..c32c90f4bf --- /dev/null +++ b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md @@ -0,0 +1,245 @@ +# Migration guide from 3.0.0-beta.20 to 3.0.0 + +Upgrading your strapi application to `3.0.0`. + +**Make sure your server is not running until the end of the migration** + +## Upgrading your dependencies + +Start by upgrading your dependencies. Make sure to use exact versions. + +Update your package.json accordingly: + +```json +{ + // ... + "dependencies": { + "strapi": "3.0.0", + "strapi-admin": "3.0.0", + "strapi-connector-bookshelf": "3.0.0", + "strapi-plugin-content-manager": "3.0.0", + "strapi-plugin-content-type-builder": "3.0.0", + "strapi-plugin-email": "3.0.0", + "strapi-plugin-graphql": "3.0.0", + "strapi-plugin-upload": "3.0.0", + "strapi-plugin-users-permissions": "3.0.0", + "strapi-utils": "3.0.0" + } +} +``` + +Then run either `yarn install` or `npm install`. + +## New configuration loader + +We have reworked the way a strapi project is configured to make it simpler yet more powerfull. + +Some of the improvements are: + +- `.env` support. +- Less files. +- Environment overwrites. + +Before migrating, you should first read the new [configuration documentation](../concepts/configurations.md). + +### Migrating + +**Server** + +Your server configuration can move from `./config/environments/{env}/server.json` to `./config/server.js` like shown [here](../concepts/configurations.md#server). + +**Database configuration** + +Your database configuration can move from `./config/environments/{env}/database.json` to `./config/database.js` like shown [here](../concepts/configurations.md#database). + +**Middlewares** + +We have moved all the middleware related configurations into one place: `./config/middleware.js`. + +The middlewares were configured in mutliple files: + +- `./config/middleware.json` +- `./config/application.json` +- `./config/language.json` +- `./config/environments/{env}/request.json` +- `./config/environments/{env}/response.json` +- `./config/environments/{env}/security.json` + +First you can create a file `./config/middleware.js`. + +```js +module.exports = { + timeout: 100, + load: { + before: ['responseTime', 'logger', 'cors', 'responses', 'gzip'], + order: [ + "Define the middlewares' load order by putting their name in this array is the right order", + ], + after: ['parser', 'router'], + }, + settings: { + public: { + path: './public', + maxAge: 60000, + }, + }, +}; +``` + +You can now move the middleware configurations from `application.json`, `language.json`, `security.json`, `request.json` and `response.json` files directly into the `settings` property. + +You can review all possible options the [middleware documentation](../concepts/middlewares.md#configuration-and-activation). + +::: tip +If you never configured any middlewares you can delete the file all together. You can also only set the configurations you want to customize and leave the others out. +::: + +**Hook** + +We applied the same logic from the `middleware` configuration to the `hook` configuration. + +First you can create a file `./config/hook.js`, and you can move the content of `./config/.hook.json` into it. + +::: tip +If you never configured any hook you can delete the file all together. You can also only set the configurations you want to customize and leave the others out. +::: + +**Functions** + +You can leave your functions as is, we didn't change how they work. + +**Policies** + +You can leave your policies as is, we didn't change how they work. + +**Custom** + +Any custom configuration you have can still be used. You can read the [configuration documentation](../concepts/configurations.md) to know more. + +**Plugin** + +From now on, you can set your plugin configurations in `./config/plugins.js` or `./config/env/{env}/plugin.js`. + +**Example** + +```js +module.exports = { + graphql: { + depthLimit: 5, + }, +}; +``` + +## Database lifecycles + +We have replaced the old lifecycles that add a lot of issues with a new simpler lifecycle layer. + +You can read more [here](../concepts/models.md#lifecycle-hooks). + +## Email plugin settings + +Email plugin settings have been moved to files. Now you can configure your email provider directly in files. + +You can read the documentation [here](../plugins/email.md#configure-the-plugin) to update. + +## GraphQL changes + +If you are using the graphql `register` mutation, the input and response types have changed. You can check the code [here](https://github.com/strapi/strapi/pull/6047). + +## Remove `idAttribute` and `idAttributeType` options. + +Currently using the idAttribute and idAttributeType options can break strapi in many ways. Fixing this is going to require a lot of work on the database and content management layer. + +In an effort to make strapi more stable we have decided to remove those broken options for the time being. For users who want unique uuid fields for examples we recommend you create a uuid attribute and use the lifecycles function to populate it. + +## Proxy configuration + +In order to support hosting strapi with more flexibility, we have changed the way to configure the server proxy options and the admin panel path. + +### Proxy + +We replaced the `proxy` option found in `./config/server.json` by the `url` option. + +This option also makes the `admin.build.backend` option obsolete. + +This option tells strapi where it is hosted and is usefull for generating links or telling the admin panel where the API is available. + +**Before** + +**Path —** `./config/server.json` + +```json +{ + "proxy": { + "enabled": true, + "ssl": true, + "host": "domain.com", + "port": "1337" + } +} +``` + +**After** + +**Path —** `./config/server.js` + +```js +module.exports = { + //... + url: `https://domain.com:1337`, +}; +``` + +What you can now do is add a path to the url to host strapi in a sub path of your domain. + +```js +module.exports = { + //... + url: `https://domain.com:1337/my-strapi-api`, +}; +``` + +::: warning +Adding a sub path to the url doesn't mean your api is going to be prefixed. You will need to host your app behind a proxy and remove the prefix so strapi receives request like if they where made on the root `/` path. +::: + +You can see this option in action in the following [deployment guide](../deployment/nginx-proxy.md). + +### Admin path + +We replaced the `admin.path` option by the `admin.url` option to offer more flexibility of deployment. + +The `url` option can either be a relative path: `/admin-panel` or an absolute url. + +**Before** + +**Path —** `./config/server.json` + +```json +{ + "admin": { + "path": "/dashboard" + } +} +``` + +**After** + +**Path —** `./config/server.js` + +```js +module.exports = { + //... + admin: { + url: '/dashboard', + }, +}; +``` + +You can see this option in action in the following [deployment guide](../deployment/nginx-proxy.md). + +## Rebuilding your administration panel + +You can run `yarn build --clean` or `npm run build -- --clean` to rebuild your admin panel with the newly installed version of strapi. + +Finally restart your server: `yarn develop` or `npm run develop`. diff --git a/docs/3.0.0-beta.x/plugins/upload.md b/docs/3.0.0-beta.x/plugins/upload.md index 4a2e0b8ccf..473a9eb1b5 100644 --- a/docs/3.0.0-beta.x/plugins/upload.md +++ b/docs/3.0.0-beta.x/plugins/upload.md @@ -310,20 +310,22 @@ or $ yarn add strapi-provider-upload-aws-s3 ``` -To enable the provider, create or edit the file at `./extensions/upload/config/settings.json` +To enable the provider, create or edit the file at `./config/plugins.js` -```json -{ - "provider": "aws-s3", - "providerOptions": { - "accessKeyId": "dev-key", - "secretAccessKey": "dev-secret", - "region": "aws-region", - "params": { - "Bucket": "my-bucket" - } +```js +module.exports = ({ env }) => ({ + upload: { + provider: 'aws-s3' + providerOptions: { + accessKeyId: env('AWS_ACCESS_KEY_ID')', + secretAccessKey: env('AWS_ACCESS_SECRET'), + region: 'aws-region', + params: { + Bucket: 'my-bucket', + }, + }, } -} +}); ``` Make sure to read the provider's `README` to know what are the possible parameters. @@ -332,23 +334,7 @@ Make sure to read the provider's `README` to know what are the possible paramete When configuring your upload provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. -You can do so using a `settings.js` file: - -```js -if (process.env.NODE_ENV === 'production') { - module.exports = { - provider: 'providerName', - providerOptions: { - cloud_name: process.env.PROVIDER_CLOUD_NAME, - api_key: process.env.PROVIDER_API_KEY, - api_secret: process.env.PROVIDER_API_SECRET, - }, - }; -} else { - // to use the default local provider you can return an empty configuration - module.exports = {}; -} -``` +You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the one in the default configuration. ## Create providers diff --git a/packages/strapi/lib/core/load-middlewares.js b/packages/strapi/lib/core/load-middlewares.js index fa0fc3e2a9..ac2e176c94 100644 --- a/packages/strapi/lib/core/load-middlewares.js +++ b/packages/strapi/lib/core/load-middlewares.js @@ -17,18 +17,16 @@ module.exports = async function(strapi) { const loaders = createLoaders(strapi); - await Promise.all([ - // load installed middlewares - loaders.loadMiddlewareDependencies(installedMiddlewares, middlewares), - // internal middlewares - loaders.loadInternalMiddlexares(middlewares), - // local middleware - loaders.loadLocalMiddlewares(appPath, middlewares), - // plugins middlewares - loaders.loadPluginsMiddlewares(installedPlugins, middlewares), - // local plugin middlewares - loaders.loadLocalPluginsMiddlewares(appPath, middlewares), - ]); + // load installed middlewares + await loaders.loadMiddlewareDependencies(installedMiddlewares, middlewares); + // internal middlewares + await loaders.loadInternalMiddlexares(middlewares); + // local middleware + await loaders.loadLocalMiddlewares(appPath, middlewares); + // plugins middlewares + await loaders.loadPluginsMiddlewares(installedPlugins, middlewares); + // local plugin middlewares + await loaders.loadLocalPluginsMiddlewares(appPath, middlewares); return middlewares; }; From 02fcbf8f452344c796e662e85ee5bc4c52754d39 Mon Sep 17 00:00:00 2001 From: Alexandre Bodin Date: Mon, 25 May 2020 14:38:54 +0200 Subject: [PATCH 2/4] Update more configs Signed-off-by: Alexandre Bodin --- .../migration-guide-beta.20-to-3.0.0.md | 4 ++-- docs/3.0.0-beta.x/plugins/graphql.md | 23 +++++++++++-------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md index c32c90f4bf..9b1f40d709 100644 --- a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md +++ b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md @@ -203,7 +203,7 @@ module.exports = { Adding a sub path to the url doesn't mean your api is going to be prefixed. You will need to host your app behind a proxy and remove the prefix so strapi receives request like if they where made on the root `/` path. ::: -You can see this option in action in the following [deployment guide](../deployment/nginx-proxy.md). +You can see this option in action in the following [deployment guide](../getting-started/deployment.md#optional-software-guides). ### Admin path @@ -236,7 +236,7 @@ module.exports = { }; ``` -You can see this option in action in the following [deployment guide](../deployment/nginx-proxy.md). +You can see this option in action in the following [deployment guide](../getting-started/deployment.md#optional-software-guides). ## Rebuilding your administration panel diff --git a/docs/3.0.0-beta.x/plugins/graphql.md b/docs/3.0.0-beta.x/plugins/graphql.md index 1a82989a1c..d3e3c6fc43 100644 --- a/docs/3.0.0-beta.x/plugins/graphql.md +++ b/docs/3.0.0-beta.x/plugins/graphql.md @@ -50,17 +50,20 @@ You can also enable the Apollo server tracing feature, which is supported by the You can edit these configurations by creating following file. -**Path —** `./extensions/graphql/config/settings.json` +**Path —** `./config/plugins.js` -```json -{ - "endpoint": "/graphql", - "tracing": false, - "shadowCRUD": true, - "playgroundAlways": false, - "depthLimit": 7, - "amountLimit": 100 -} +```js +module.exports = { + // + graphql: { + endpoint: '/graphql', + tracing: false, + shadowCRUD: true, + playgroundAlways: false, + depthLimit: 7, + amountLimit: 100, + }, +}; ``` ## Query API From 9078081ebaf5dc4a19aecd01e03bcdda107ebf92 Mon Sep 17 00:00:00 2001 From: Alexandre Bodin Date: Mon, 25 May 2020 14:48:39 +0200 Subject: [PATCH 3/4] Add strucutre example Signed-off-by: Alexandre Bodin --- .../migration-guide-beta.20-to-3.0.0.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md index 9b1f40d709..0a47c7eb00 100644 --- a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md +++ b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md @@ -130,6 +130,75 @@ module.exports = { }; ``` +### Final strucutre + +Here is an example of the strucuture you could have after migrating: + +**Before** + +``` +config +├── application.json +├── custom.json +├── environments +│   ├── development +│   │   ├── custom.json +│   │   ├── database.json +│   │   ├── request.json +│   │   ├── response.json +│   │   ├── security.json +│   │   └── server.json +│   ├── production +│   │   ├── custom.json +│   │   ├── database.json +│   │   ├── request.json +│   │   ├── response.json +│   │   ├── security.json +│   │   └── server.json +│   └── staging +│   ├── custom.json +│   ├── database.json +│   ├── request.json +│   ├── response.json +│   ├── security.json +│   └── server.json +├── functions +│   ├── bootstrap.js +│   ├── cron.js +│   └── responses +│   └── 404.js +├── hook.json +├── language.json +├── locales +│   ├── cs_cz.json +│   ├── de_de.json +│   ├── en_us.json +│   ├── es_es.json +│   ├── fr_fr.json +│   ├── it_it.json +│   ├── ja_jp.json +│   ├── ru_ru.json +│   └── tr_tr.json +└── middleware.json +``` + +**After** + +``` +config +├── functions +│   ├── bootstrap.js +│   ├── cron.js +│   └── responses +│   └── 404.js +├── env +│   └── production +│   └── database.js +├── database.js +├── middleware.js +└── server.js +``` + ## Database lifecycles We have replaced the old lifecycles that add a lot of issues with a new simpler lifecycle layer. From 7df82f5e62df6913667a9505270b58a53e0e6053 Mon Sep 17 00:00:00 2001 From: Alexandre Bodin Date: Mon, 25 May 2020 15:27:33 +0200 Subject: [PATCH 4/4] Add cleanup instruction Signed-off-by: Alexandre Bodin --- .../migration-guide/migration-guide-beta.20-to-3.0.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md index 0a47c7eb00..59726ff435 100644 --- a/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md +++ b/docs/3.0.0-beta.x/migration-guide/migration-guide-beta.20-to-3.0.0.md @@ -211,6 +211,8 @@ Email plugin settings have been moved to files. Now you can configure your email You can read the documentation [here](../plugins/email.md#configure-the-plugin) to update. +Once you have setup your configuration, you can cleanup your database by deleting in the `core_store` model the data with the `key` equal to `plugin_email_provider`. + ## GraphQL changes If you are using the graphql `register` mutation, the input and response types have changed. You can check the code [here](https://github.com/strapi/strapi/pull/6047).