diff --git a/.vuepress/config.js b/.vuepress/config.js index 5b957c31..03d85c29 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -43,6 +43,7 @@ module.exports = { children: [ '/panel/getting_started', '/panel/webserver_configuration', + '/panel/upgrading', ] }, { diff --git a/package.json b/package.json index 83692ced..216fd417 100644 --- a/package.json +++ b/package.json @@ -5,5 +5,8 @@ "scripts": { "build": "./node_modules/vuepress/bin/vuepress.js build", "watch": "./node_modules/vuepress/bin/vuepress.js dev" + }, + "devDependencies": { + "lodash": "^4.17.10" } } diff --git a/panel/upgrade/0.6_to_0.7.md b/panel/upgrade/0.6_to_0.7.md new file mode 100644 index 00000000..35349d92 --- /dev/null +++ b/panel/upgrade/0.6_to_0.7.md @@ -0,0 +1,105 @@ +# Upgrading 0.6 to 0.7 + +## Fetch Updated Files +The first step in the update process is to download the new panel files from Github. The command below will download +the release archive for the most recent version of Pterodactyl and save it in the current directory. Now is a good time +to ensure that you're in the `/var/www/pterodactyl` directory as the command below will automatically unpack in whatever +directory you are currently in. + +``` bash +curl -L https://github.com/pterodactyl/panel/releases/download/v0.7.9/panel.tar.gz | tar --strip-components=1 -xzv +``` + +Once all of the files are downloaded we need to set the correct permissions on the cache and storage directories to avoid +any webserver related errors. + +``` bash +chmod -R 755 storage/* bootstrap/cache +``` + +## Clear Compiled Assets +Previous versions of Pterodactyl attempted to cache your configuration file for speed and performance enhancements. This +ended up just causing more headaches with minimal improvements in performance, so we decided to stop doing that. Running +the command below will clear the cached files for you so we can continue with upgrading. + +::: tip +You probably only need to run this command once when upgrading from `0.6.X`. Once you're upgraded we don't cache the configuration +file so there is no reason to remove anything. +::: + +``` bash +rm -rf bootstrap/cache/* +``` + +Once the configuration cache is removed, you'll need to clear the template cache to ensure users get the most recent +templates. + +``` bash +php artisan view:clear +``` + +## Update Dependencies +After you've downloaded all of the new files you will need to upgrade the core components of the panel. To do this, +simply run the commands below and follow any prompts. + +``` bash +composer install --no-dev --optimize-autoloader +``` + +## Update Environment +These scripts will display your current values in brackets. To keep the current values simply press enter and it will +continue without making any modifications. + +::: tip +We've changed our recommended cache driver to be Redis, rather than Memcached. If you're using Memcached you can +continue doing so with no problems, however moving forward our installation documentation will only mention Redis. +::: + +``` bash +php artisan p:environment:setup +php artisan p:environment:mail +php artisan p:environment:database +``` + +## Database Updates + +::: warning Backup your databases +The upgrade from `0.6` to `v0.7` includes some rather significant database changes. While the migration utility is +able to handle everything for you, we still suggest taking a backup of your database before proceeding — just incase. +::: + +::: warning +Running `db:seed` below will overwrite any changes you made to core Pterodactyl Nests, Eggs, or Egg Variables! This is +unavoidable, and this seeder must be run. To avoid this in the future, please create custom nests, or create custom +eggs for game variations. +::: +``` bash +php artisan migrate --force +php artisan db:seed --force +``` + +## Cleanup API Keys +A significant change is introduced in 0.7.0 that changes how API keys are used, stored, and validated. Due to this +change, all previously created keys will no longer function. In order to keep things cleaned up you'll want to remove +these orphaned keys. To do so, run the command below. + +``` bash +php artisan p:migration:clean-orphaned-keys +``` + +Don't forget to create new keys for yourself, as well as let all of your users know they'll need to do so as well. + +## Set Permissions +The last step is to set the proper owner of the files to be the user that runs your webserver. In most cases this +is `www-data` but can vary from system to system — sometimes being `nginx`, `apache`, or even `nobody`. + +``` bash +# If using NGINX or Apache (not on CentOS): +chown -R www-data:www-data * + +# If using NGINX on CentOS: +chown -R nginx:nginx * + +# If using Apache on CentOS +chown -R apache:apache * +``` diff --git a/panel/upgrade/0.7.md b/panel/upgrade/0.7.md new file mode 100644 index 00000000..35431b9f --- /dev/null +++ b/panel/upgrade/0.7.md @@ -0,0 +1,60 @@ +# Upgrading 0.7 Series +This documentation covers the process for upgrading within the `0.7.X` series of releases. This means upgrading from +— for example — `0.7.3` to `0.7.9`. **Do not use this guide for upgrading from `0.6` or upgrading to `0.8`.** + +## Fetch Updated Files +The first step in the update process is to download the new panel files from Github. The command below will download +the release archive for the most recent version of Pterodactyl and save it in the current directory. Now is a good time +to ensure that you're in the `/var/www/pterodactyl` directory as the command below will automatically unpack the archive +into your current folder. + +``` bash +curl -L https://github.com/pterodactyl/panel/releases/download/v0.7.9/panel.tar.gz | tar --strip-components=1 -xzv +``` + +Once all of the files are downloaded we need to set the correct permissions on the cache and storage directories to avoid +any webserver related errors. + +``` bash +chmod -R 755 storage/* bootstrap/cache +``` + +## Update Dependencies +After you've downloaded all of the new files you will need to upgrade the core components of the panel. To do this, +simply run the commands below and follow any prompts. + +``` bash +composer install --no-dev --optimize-autoloader +``` + +## Clear Compiled Template Cache +You'll also want to clear the compiled template cache to ensure that new and modified templates show up correctly for +users. + +``` bash +php artisan view:clear +``` + +## Database Updates +You'll also need to update your database schema for the newest version of Pterodactyl. Running the two commands below +will update the schema and ensure the default eggs we ship are up to date (and add any new ones we might have). Just +remember, _never edit core eggs we ship_! They will be overwritten by this update process. +``` bash +php artisan migrate --force +php artisan db:seed --force +``` + +## Set Permissions +The last step is to set the proper owner of the files to be the user that runs your webserver. In most cases this +is `www-data` but can vary from system to system — sometimes being `nginx`, `apache`, or even `nobody`. + +``` bash +# If using NGINX or Apache (not on CentOS): +chown -R www-data:www-data * + +# If using NGINX on CentOS: +chown -R nginx:nginx * + +# If using Apache on CentOS +chown -R apache:apache * +``` diff --git a/panel/upgrading.md b/panel/upgrading.md new file mode 100644 index 00000000..095c4569 --- /dev/null +++ b/panel/upgrading.md @@ -0,0 +1,36 @@ +# Upgrading +Upgrading the Panel is a relatively simple process. Below you will find a list of articles that will walk you through +the upgrade process for each version of the software. + +## Maintenance Mode +Whenever you are performing an upgrade you should be sure to place your Panel into maintenance mode. This will prevent +users from encountering unexpected errors and ensure everything can be upgraded before users being encountering +potentially new features. + +``` bash +# Put the Panel into maintenance mode and deny user access +php artisan down + +# Bring the Panel back up to receive connections. +php artisan up +``` + +## Restarting Queue Workers +After _every_ update you should restart the queue worker to ensure that the new code is loaded in and used. + +``` bash +php artisan queue:restart +``` + +## Version Specific Guides + +* [0.6.X to 0.7.9](/panel/upgrade/0.6_to_0.7.md) +* [0.7.X series](/panel/upgrade/0.7.md) +* [0.7.X to 0.8.0](#) + + diff --git a/yarn.lock b/yarn.lock index d70e3bcb..175c280f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3462,7 +3462,7 @@ lodash.uniq@^4.5.0: version "4.5.0" resolved "https://registry.yarnpkg.com/lodash.uniq/-/lodash.uniq-4.5.0.tgz#d0225373aeb652adc1bc82e4945339a842754773" -lodash@^4.17.3, lodash@^4.17.4, lodash@^4.17.5: +lodash@^4.17.10, lodash@^4.17.3, lodash@^4.17.4, lodash@^4.17.5: version "4.17.10" resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.10.tgz#1b7793cf7259ea38fb3661d4d38b3260af8ae4e7"