Skip to main content

5.0.0-beta.4 to 5.0.0

What you’ll learn
  • how to upgrade Webiny from 5.0.0-beta.4 to 5.0.0

How to Upgrade#

danger

When deploying to production environments, in order to prevent data loss, make sure to backup data stored in your ElasticSearch and DynamoDB databases!

This is mainly because of the changes introduced by the pulumi.zip file, mentioned below. Once you paste the code into your project, the first production environment deployment will:

  • deploy a custom Virtual Private Network (VPC)
  • deploy your ElasticSearch cluster into multiple availability zones (AZs)

If you want to continue deploying the same infrastructure you already had in place for the production environment, make sure to comment out or remove the following if statement:

api/pulumi/index.ts:10
if (process.env.WEBINY_ENV === "prod") {
// Import "prod" resources config and initialize resources.
return await import("./prod").then(module => module.default());
}

In any case, if you have any additional questions or concerns, please don't hesitate to send us a message via our community Slack channel.

caution

This guide contains many manual steps. If the circumstances allow it, we recommend you create a new Webiny 5.0.0 project from scratch.

If you still want to upgrade your project manually, follow the steps below in the exact order.

File paths

All file paths in the instructions below are considered to start in your project root directory.

Upgrade Yarn#

Webiny now works with yarn 2 exclusively. It's a big improvement over yarn 1.x in both speed and reliability when it comes to package upgrades.

  • run the following command in the root of your Webiny project:
yarn set version berry
  • edit .yarnrc.yml and add nodeLinker: node-modules config option.

  • run the following to migrate the yarn.lock file:

yarn install

Upgrade Project Files#

Now we need to apply some changes to the project itself:

  • edit package.json and add the following resolutions, workspaces and dependencies (keep the existing values, and add the new ones in):
{
"dependencies": {
// ...
"@webiny/cli-plugin-scaffold": "5.0.0",
"@webiny/cli-plugin-scaffold-graphql-service": "5.0.0",
"@webiny/cli-plugin-scaffold-admin-app-module": "5.0.0"
},
"resolutions": {
"@types/react": "16.14.4",
"react": "16.14.0",
"react-dom": "16.14.0"
},
"workspaces": {
"packages": [
// ...
"api/code/dynamoToElastic"
]
}
}
  • add "@webiny/cli": "5.0.0" to dependencies in the following files:

    • apps/admin/code/package.json
    • apps/website/code/package.json
  • editapps/theme/package.json and remove the publishConfig section completely.

  • download dynamoToElastic.zip, unzip it, and put into api/code/dynamoToElastic. You may need to create this folder yourself, depending on how you extracted the archive. The end result should look like this:

dynamoToElastic folder after upgrade
Be careful!

In the next step, don't mistake pulumi for your .pulumi folder! We want to replace the infrastructure definitions, but keep the state files.

  • download pulumi.zip, unzip it, and completely replace your existing api/pulumi folder with the one in the archive (don't worry, your existing infrastructure will be intact). The end result should look like this:
pulumi folder after upgrade
  • edit api/code/graphql/src/index.ts and replace the contents of it with the following:
import { DocumentClient } from "aws-sdk/clients/dynamodb";
import { createHandler } from "@webiny/handler-aws";
import graphqlPlugins from "@webiny/handler-graphql";
import i18nPlugins from "@webiny/api-i18n/graphql";
import i18nContentPlugins from "@webiny/api-i18n-content/plugins";
import pageBuilderPlugins from "@webiny/api-page-builder/graphql";
import dbPlugins from "@webiny/handler-db";
import { DynamoDbDriver } from "@webiny/db-dynamodb";
import elasticSearch from "@webiny/api-plugin-elastic-search-client";
import fileManagerPlugins from "@webiny/api-file-manager/plugins";
import prerenderingServicePlugins from "@webiny/api-prerendering-service/client";
// File storage S3 plugin for API file manager.
import fileManagerS3 from "@webiny/api-file-manager-s3";
import formBuilderPlugins from "@webiny/api-form-builder/plugins";
import securityPlugins from "./security";
import headlessCmsPlugins from "@webiny/api-headless-cms/plugins";
export const handler = createHandler(
graphqlPlugins({ debug: process.env.DEBUG }),
elasticSearch({ endpoint: `https://${process.env.ELASTIC_SEARCH_ENDPOINT}` }),
dbPlugins({
table: process.env.DB_TABLE,
driver: new DynamoDbDriver({
documentClient: new DocumentClient({
convertEmptyValues: true,
region: process.env.AWS_REGION
})
})
}),
securityPlugins(),
i18nPlugins(),
i18nContentPlugins(),
fileManagerPlugins(),
// Add File storage S3 plugin for API file manager.
fileManagerS3(),
prerenderingServicePlugins({
handlers: {
render: process.env.PRERENDERING_RENDER_HANDLER,
flush: process.env.PRERENDERING_FLUSH_HANDLER,
queue: {
add: process.env.PRERENDERING_QUEUE_ADD_HANDLER,
process: process.env.PRERENDERING_QUEUE_PROCESS_HANDLER
}
}
}),
pageBuilderPlugins(),
formBuilderPlugins(),
headlessCmsPlugins()
);
  • edit the following files and remove the backend section:

    • api/Pulumi.yaml
    • apps/admin/Pulumi.yaml
    • apps/website/Pulumi.yaml
  • edit webiny.root.js and add the following to the plugins array (these are the new scaffolding plugins 🎉):

require("@webiny/cli-plugin-scaffold").default(),
require("@webiny/cli-plugin-scaffold-graphql-service").default(),
require("@webiny/cli-plugin-scaffold-admin-app-module").default();
  • run the following command to remove all node_modules from your project:
npx rimraf **/node_modules
  • upgrade Webiny packages to 5.0.0 by running:
yarn up "@webiny/*@5.0.0"

Congratulations! 🎉 This is all you need to do with your project files. Now you can deploy your project, open your admin app and go through the upgrade wizard which will migrate your data and Elasticsearch indexes.

Optional Steps#

If you plan to develop your own packages, and run Jest tests, you'll want to apply these changes as well:

  • edit .env and add DEBUG=true to enable log streaming to your browser and add extra debug logs to CloudWatch

  • edit jest.config.js and replace the entire file contents with the following:

const fs = require("fs");
const path = require("path");
const { allWorkspaces } = require("@webiny/project-utils/workspaces");
const { version } = require("@webiny/cli/package.json");
process.env.DB_TABLE_ELASTICSEARCH = "ElasticSearchStream";
process.env.WEBINY_VERSION = version;
const projects = allWorkspaces()
.map(pkg => {
if (!fs.existsSync(path.join(pkg, "jest.config.js"))) {
return null;
}
return pkg.replace(process.cwd() + "/", "");
})
.filter(Boolean);
module.exports = {
projects,
modulePathIgnorePatterns: ["dist"]
};
  • create a jest-es-config.js file and put this inside:
module.exports = () => {
return {
esVersion: "7.6.0",
clusterName: "test-cluster",
nodeName: "test-node",
port: 9200,
indexes: []
};
};
Last updated on by Adrian Smijulj