{"ArticleId":null,"Name":"Upgrading to a new version","Content":"\u003Cp\u003EUpgrading GrandNode means replacing the application files with a newer version and starting it against your existing database. You do not run any scripts yourself: on startup GrandNode compares the database version with its own and runs the database migrations that are missing. This article explains how that works and the steps for Docker and for a self-built installation.\u003C/p\u003E\n\n\u003Ch2 id=\u0022how-migrations-work\u0022\u003EHow migrations work\u003C/h2\u003E\n\u003Cp\u003EThe database remembers which GrandNode version it was last upgraded to (in the version collection), and every migration that has run is recorded in a migrations collection. When the application starts:\u003C/p\u003E\n\u003Col\u003E\n\u003Cli\u003EThe migration module (\u003Ccode\u003EGrand.Module.Migration\u003C/code\u003E, enabled in \u003Ccode\u003EFeatureManagement\u003C/code\u003E in \u003Ccode\u003Eappsettings.json\u003C/code\u003E) reads the installed version.\u003C/li\u003E\n\u003Cli\u003EIt takes all migrations of \u003Cem\u003Enewer\u003C/em\u003E versions, in version order, and skips those already recorded.\u003C/li\u003E\n\u003Cli\u003EIt runs each one \u2014 adding new permissions, admin menu entries, translation resources, settings, indexes, or reshaping data \u2014 and records it.\u003C/li\u003E\n\u003Cli\u003EThe last migration of each version stamps the database with that version.\u003C/li\u003E\n\u003C/ol\u003E\n\u003Cp\u003EBecause the migrations are ordered by version, you can skip releases: upgrading from 2.2 to 2.4 runs the 2.3 and 2.4 migrations in turn. If a migration fails, the process stops before the version is stamped, the error is written to the log, and it is retried on the next start.\u003C/p\u003E\n\u003Cp\u003EA request only reaches your store when the database version matches the application (major.minor). Otherwise every page shows \u201CThe database version is not supported in this software version\u201D, with both versions. This is what you see if migrations failed or were switched off.\u003C/p\u003E\n\n\u003Ch2 id=\u0022before-you-upgrade\u0022\u003EBefore you upgrade\u003C/h2\u003E\n\u003Cul\u003E\n\u003Cli\u003E\u003Cstrong\u003ERead the release notes\u003C/strong\u003E for every version between yours and the target \u2014 the installed version is shown under the \u003Cstrong\u003EHelp\u003C/strong\u003E menu and in \u003Cstrong\u003ESystem \u2192 System information\u003C/strong\u003E.\u003C/li\u003E\n\u003Cli\u003E\u003Cstrong\u003EBack up the database\u003C/strong\u003E with \u003Ccode\u003Emongodump\u003C/code\u003E (or your hosting\u0027s snapshot). Migrations change data and there is no automatic downgrade.\u003C/li\u003E\n\u003Cli\u003E\u003Cstrong\u003EBack up\u003C/strong\u003E \u003Ccode\u003EApp_Data\u003C/code\u003E (\u003Ccode\u003ESettings.cfg\u003C/code\u003E, \u003Ccode\u003Eappsettings.json\u003C/code\u003E) and \u003Ccode\u003Ewwwroot/assets/images\u003C/code\u003E if images are stored on disk.\u003C/li\u003E\n\u003Cli\u003E\u003Cstrong\u003EList your own plugins and themes\u003C/strong\u003E. They must be rebuilt against the new version.\u003C/li\u003E\n\u003Cli\u003ETry the upgrade on a copy of the database first when the store is live.\u003C/li\u003E\n\u003C/ul\u003E\n\n\u003Ch2 id=\u0022upgrade-docker\u0022\u003EUpgrade a Docker installation\u003C/h2\u003E\n\u003Col\u003E\n\u003Cli\u003EPull the new image: \u003Ccode\u003Edocker pull grandnode/grandnode2:x.xx\u003C/code\u003E (or \u003Ccode\u003Elatest\u003C/code\u003E).\u003C/li\u003E\n\u003Cli\u003EStop and remove the old container: \u003Ccode\u003Edocker stop grandnode2\u003C/code\u003E, \u003Ccode\u003Edocker rm grandnode2\u003C/code\u003E.\u003C/li\u003E\n\u003Cli\u003EStart the new one with the same volumes, so \u003Ccode\u003EApp_Data\u003C/code\u003E and images are kept:\n\u003Cpre\u003E\u003Ccode\u003Edocker run -d -p 80:8080 --name grandnode2 --link mongodb:mongo \\\n  -v grandnode_images:/app/wwwroot/assets/images \\\n  -v grandnode_appdata:/app/App_Data \\\n  grandnode/grandnode2:x.xx\u003C/code\u003E\u003C/pre\u003E\u003C/li\u003E\n\u003Cli\u003EWatch the log (\u003Ccode\u003Edocker logs -f grandnode2\u003C/code\u003E) for lines such as \u201CThe migration of \u2026 has been completed successfully.\u201D\u003C/li\u003E\n\u003C/ol\u003E\n\u003Cp\u003ENote that the image\u0027s \u003Ccode\u003Eappsettings.json\u003C/code\u003E lives in the \u003Ccode\u003EApp_Data\u003C/code\u003E volume: new settings added in the new version are not merged into your existing file. Compare it with the file in the release and copy new sections over.\u003C/p\u003E\n\n\u003Ch2 id=\u0022upgrade-self-built\u0022\u003EUpgrade a self-built installation\u003C/h2\u003E\n\u003Col\u003E\n\u003Cli\u003EGet the new version: download the release package or \u003Ccode\u003Egit checkout\u003C/code\u003E the release tag.\u003C/li\u003E\n\u003Cli\u003EBuild it exactly as for a new installation \u2014 the solution, or modules and plugins followed by \u003Ccode\u003Edotnet publish\u003C/code\u003E (see \u003Ca href=\u0022/getting-started-installing\u0022\u003EInstalling GrandNode\u003C/a\u003E).\u003C/li\u003E\n\u003Cli\u003EStop the site.\u003C/li\u003E\n\u003Cli\u003EReplace the application files with the new build, but keep your \u003Ccode\u003EApp_Data/Settings.cfg\u003C/code\u003E, your \u003Ccode\u003Eappsettings.json\u003C/code\u003E changes and the uploaded images. Merge new settings from the new \u003Ccode\u003Eappsettings.json\u003C/code\u003E into yours.\u003C/li\u003E\n\u003Cli\u003ECopy in your own plugins and themes, rebuilt against the new version.\u003C/li\u003E\n\u003Cli\u003EStart the site and check the log for the migration messages.\u003C/li\u003E\n\u003C/ol\u003E\n\n\u003Ch2 id=\u0022after-the-upgrade\u0022\u003EAfter the upgrade\u003C/h2\u003E\n\u003Cul\u003E\n\u003Cli\u003ESign in to the Admin panel and check \u003Cstrong\u003ESystem \u2192 System information\u003C/strong\u003E for the new version and for warnings.\u003C/li\u003E\n\u003Cli\u003EOpen \u003Cstrong\u003EPlugins \u2192 Local plugins\u003C/strong\u003E and confirm your plugins are still installed.\u003C/li\u003E\n\u003Cli\u003EIf the admin menu or texts look outdated, use \u003Cstrong\u003EClear memory cache\u003C/strong\u003E under the gear icon in the top bar.\u003C/li\u003E\n\u003Cli\u003EPlace a test order.\u003C/li\u003E\n\u003C/ul\u003E\n\n\u003Ch2 id=\u0022tips-and-common-mistakes\u0022\u003ETips and common mistakes\u003C/h2\u003E\n\u003Cul\u003E\n\u003Cli\u003E\u003Cstrong\u003E\u201CThe database version is not supported\u201D\u003C/strong\u003E \u2014 the migrations did not finish. Check the log for the failing migration, fix the cause and restart; it will be retried. Make sure \u003Ccode\u003EGrand.Module.Migration\u003C/code\u003E is \u003Ccode\u003Etrue\u003C/code\u003E in \u003Ccode\u003EFeatureManagement\u003C/code\u003E.\u003C/li\u003E\n\u003Cli\u003E\u003Cstrong\u003EDo not run the installation wizard\u003C/strong\u003E to upgrade \u2014 it is only for new databases.\u003C/li\u003E\n\u003Cli\u003E\u003Cstrong\u003EDo not go back\u003C/strong\u003E to an older version on a migrated database; restore the backup instead.\u003C/li\u003E\n\u003Cli\u003ESeveral application instances sharing one database: upgrade them together, start one first and let it finish the migrations.\u003C/li\u003E\n\u003C/ul\u003E\n\n\u003Ch2 id=\u0022related\u0022\u003ERelated\u003C/h2\u003E\n\u003Cul\u003E\n\u003Cli\u003E\u003Ca href=\u0022/getting-started-installing\u0022\u003EInstalling GrandNode\u003C/a\u003E\u003C/li\u003E\n\u003Cli\u003E\u003Ca href=\u0022/getting-started-system-requirements\u0022\u003ESystem requirements\u003C/a\u003E\u003C/li\u003E\n\u003C/ul\u003E","ParentCategoryId":"6abdec6c83d2816248229ea1","SeName":"getting-started-upgrading","MetaKeywords":null,"MetaDescription":"Upgrade GrandNode safely: back up MongoDB and App_Data, replace the application, and let the database migrations run automatically on startup.","MetaTitle":null,"AllowComments":false,"Captcha":{"ReCaptchaChallengeField":null,"ReCaptchaResponseField":null,"ReCaptchaResponseValue":null,"ReCaptchaResponse":null},"RelatedArticles":[],"CategoryBreadcrumb":[{"Name":"Getting started","Description":null,"IsCurrent":false,"Children":null,"Parent":null,"SeName":"docs-getting-started","Id":"6abdec6c83d2816248229ea1","UserFields":[]}],"AddNewComment":{"CommentText":null,"DisplayCaptcha":false,"Id":null,"UserFields":[]},"Comments":[],"Id":"6abdec6c83d2816248229eaf","UserFields":[]}