Updating the Panel
This documentation covers the process for upgrading within the
3.x series of releases. This means updating from — for example —
Before You Begin
Please backup your files before proceeding so that you can rollback in an event of a broken update. It's as simple as copying the folder that contains Convoy, and it will contain your database entries (unless you're not using Convoy's pre-configured deployment), configuration, and Convoy itself.
Though, don't immediately start backing up right now as your panel is still running. Read the rest of this documentation, and we'll tell you when it's safe.
Enter Maintenance Mode
Whenever you are performing an update you should be sure to place your Panel into maintenance mode. This will prevent users from encountering unexpected errors and ensure everything can be updated before users encounter potentially new features.
secret option to specify a maintenance mode bypass token, so you can access the queue system dashboard after setting your server into maintenance mode.
cd /var/www/convoy docker compose up -d workspace docker compose exec workspace php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
After placing Convoy in maintenance mode, you may navigate to the URL matching this token and Convoy will issue a maintenance mode bypass cookie to your browser:
When accessing this hidden route, you will then be redirected to the
/ route of Convoy. Once the cookie has been issued to your browser, you will be able to browse Convoy normally as if it was not in maintenance mode.
Check For Running Jobs
After you have set the Panel to maintenance mode, check Convoy's workers to see whether they are still processing jobs (e.g. server installations, backups, restorations). Goto
your.domain/horizon after signing into Convoy with an account that has administrator privileges. Then, check whether there are still any jobs pending or processing.
If there are pending jobs or jobs in progress, patiently wait for them to complete. If you don't wait for the jobs to complete, you risk putting servers in an unknown state and this is not the only potential consequence.
Shutting Down Containers
Once Convoy is idle, you can now safely turn off the Docker containers.
docker compose down
After turning off the containers, you may now backup Convoy.
Download the Update
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 Convoy, save it in the current directory and will automatically unpack the archive into your current folder.
curl -L https://github.com/convoypanel/panel/releases/latest/download/panel.tar.gz | tar -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.
chmod -R o+w storage/* bootstrap/cache
Now that you have the update, proceed to rebuild the Docker containers for Convoy
docker compose build --no-cache
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.
docker compose up -d workspace docker compose exec workspace composer install --no-dev --optimize-autoloader
You'll also need to update your database schema for the newest version of Convoy. Running the command below will update the schema of your database.
docker compose up -d database
Now, it will take a moment (5-10 seconds) for the database to initialize from a cold start, so be patient before running the next command.
docker compose exec workspace php artisan migrate --force
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.
docker compose up -d redis docker compose exec workspace php artisan optimize:clear docker compose exec workspace php artisan optimize
Starting the Ignition
Now that everything has been updated, you can start up the rest of the containers so that the Panel can resume accepting connections.
docker compose down docker compose up -d docker compose exec workspace php artisan up