Upgrading Versions

Introduction

NiceTryBot is released often, and updating is a single command. Before every update, NiceTryBot backs up your database, and if the new release doesn't come up healthy, it puts the previous release back on its own. This guide explains how releases are numbered, how to update, and how to roll back if you need to.

Versioning Scheme

NiceTryBot releases are tagged on GitHub as vMAJOR.MINOR.PATCH. The current release is v0.1.0. Each release's notes are published with its tag on GitHub, and each release attaches the files the installer uses: compose.yml, compose.addons.yml, install.sh, and an example environment file.

NiceTryBot is in its 0.x series, so any release may change how things work while the product settles. Always read the release notes before you update. When a release needs something from you beyond running nicetrybot update, its notes will say so.

Docker images are published to ghcr.io/nicetrybot and tagged with the bare version number, such as 0.1.0, as well as latest. Pre-releases, such as v0.2.0-beta.1, never move the latest tag.

Note

Marketplace add-ons are versioned separately from NiceTryBot itself. Updating NiceTryBot also rebuilds your add-ons with the newest versions your licence allows.

Documentation Versions

This documentation is versioned alongside NiceTryBot. The version switcher at the top of every page lists each documented series, and the docs for 0.x cover every 0.x release. When a new major series is released, its documentation will appear in the switcher, and the previous series' documentation will remain available.

Updating NiceTryBot

To update NiceTryBot to the newest release, SSH into your server and run:

Terminal

nicetrybot update

Running the installer again on a server where NiceTryBot is already running does exactly the same thing.

Updating Using AI

If an agent has access to your server, it can run the update and read the release notes for you. You may give it the following prompt:

Read https://docs.nicetrybot.com/docs/0.x/upgrade.md. Then check which NiceTryBot release my server runs with `nicetrybot version`, read the release notes for every release since then on GitHub, and tell me about anything I need to do before I update. Don't run the update until I say so.

What an Update Does

When you run nicetrybot update, NiceTryBot will:

Tell you which release it is updating from, and which it is updating to.
Back up the bundled Postgres database to /opt/nicetrybot/backups, keeping the newest three backups.
Download the new release's compose.yml, keep your .env file, and pin NICETRY_VERSION to the new release.
Pull the new images, rebuild your add-ons into the app, and restart whatever changed. The app runs any new database migrations as it starts.
Check that the app came up healthy. If it didn't, NiceTryBot puts the previous release back, including the database if migrations ran.

Docker's output is written to /opt/nicetrybot/.updates/update.log, which is the first place to look if an update doesn't go as planned.

Warning

Backups only cover the bundled Postgres service. If you use a managed database, take a snapshot with your provider before updating. You may skip NiceTryBot's own backup with --no-backup.

Updating to a Specific Release

To update to, or go back to, a specific release, pass the --version option:

Terminal

nicetrybot update --version=v0.1.0

You may check which release is running, and which is the newest, at any time:

Terminal

nicetrybot version

Rolling Back

If you are unhappy with an update, you may undo it:

Terminal

nicetrybot rollback

Rolling back restores the previous release, its compose.yml, your add-ons, and the database backup taken before the update. Because the database is restored, any changes made in the control panel since the update are lost, so the command asks for confirmation first. Pass --yes to skip the question.

Note

A managed database is never backed up or restored by nicetrybot rollback. Restore it from your provider's snapshot instead.

Update Notices

Once a day, NiceTryBot checks whether a newer release is available. When one is, administrators will see a notice in the control panel with a link to what's new. NiceTryBot never updates itself: the notice simply lets you know it's time to run nicetrybot update.

If you would rather NiceTryBot didn't check, set the following in your .env file and run nicetrybot apply:

.env

NICETRY_UPDATE_CHECK=false

Updating Manually

Docker Compose

If you manage the stack with Docker Compose yourself, set NICETRY_VERSION in your .env file to the release you want, then pull the new images and restart the stack:

Terminal

cd /opt/nicetrybot

docker compose pull
docker compose up -d --remove-orphans

If you have add-ons installed, rebuild the app image as well:

Terminal

docker pull ghcr.io/nicetrybot/app:latest
docker compose build app
docker compose up -d --remove-orphans

Remember to back up your database before updating by hand, since only nicetrybot update does it for you.

Without Docker

If you run the control panel on a plain PHP host, update it like any other Laravel application:

Terminal

git checkout composer.json composer.lock
git pull

composer install --no-dev --optimize-autoloader
php artisan addons:install
php artisan migrate --force

npm ci && npm run build
php artisan optimize

Your edge server is updated separately, by pulling the new ghcr.io/nicetrybot/edge image.