Updating Bacularis#

General notes#

Before upgrading, please read the release notes available on the Releases page of each Bacularis repository on GitHub.

Updating binary packages#

If you installed Bacularis using binary packages, the upgrade process is fully automated. No additional steps are required—just run the appropriate upgrade command using your system’s package manager.

Updating Composer-based installations#

If you installed Bacularis using Composer, please note that Bacularis stores some of its configuration files inside the vendor directory. These configurations need to be preserved during the update process. To handle this, Bacularis automatically creates a TAR archive containing your configuration and log files during the update and restores them afterward.

Important: Make sure the tar archiver is installed and available in your system’s PATH, as it’s required for this process.

Note

Before upgrading, download the latest composer.json file from the bacularis/bacularis-app GitHub repository. Replace your existing composer.json file with the downloaded one. This is necessary because Composer does not automatically update project files created using the composer create-project command.

To upgrade, you only need to run a single Composer command. There are two ways to do this:

[RECOMMENDED] run upgrade as root user#

This approach ensures that file permissions are set automatically:

composer update

[FOR ADVANCED USERS] run upgrade as regular user#

You can also run the upgrade as any user who owns or has read/write access to all files in the Bacularis project directory. After a successful upgrade, you’ll need to manually set read/write permissions for the web server user.

Here’s how to do it using the www-data user from the root account:

cd /var/www/bacularis-app
chown -R www-data:www-data .
sudo -u www-data composer update

Manual installation update#

If you installed Bacularis manually from source archives, follow these steps to upgrade:

First, set the target version using an environment variable:

BACULARIS_VER=4.7.1

Next, create a temporary directory for the new Bacularis files and navigate to it:

mkdir -p /tmp/bacularis-update
cd /tmp/bacularis-update

Now you need to download source archives containing the new Bacularis version:

wget -O bacularis-api-$BACULARIS_VER.tar.gz https://github.com/bacularis/bacularis-api/archive/refs/tags/$BACULARIS_VER.tar.gz
wget -O bacularis-common-$BACULARIS_VER.tar.gz https://github.com/bacularis/bacularis-common/archive/refs/tags/$BACULARIS_VER.tar.gz
wget -O bacularis-web-$BACULARIS_VER.tar.gz https://github.com/bacularis/bacularis-web/archive/refs/tags/$BACULARIS_VER.tar.gz
wget -O bacularis-app-$BACULARIS_VER.tar.gz https://github.com/bacularis/bacularis-app/archive/refs/tags/$BACULARIS_VER.tar.gz
wget https://bacularis.app/downloads/bacularis-external-$BACULARIS_VER.tar.gz

After that there is needed to unpack new source archives and create internal application structure:

tar --strip-components 1 -zxvf bacularis-app-$BACULARIS_VER.tar.gz
tar --strip-components 1 -C protected -zxvf bacularis-external-$BACULARIS_VER.tar.gz
mkdir -p protected/vendor/bacularis/bacularis-common
mkdir -p protected/vendor/bacularis/bacularis-api
mkdir -p protected/vendor/bacularis/bacularis-web
tar --strip-components 1 -C protected/vendor/bacularis/bacularis-common -zxvf bacularis-common-$BACULARIS_VER.tar.gz
tar --strip-components 1 -C protected/vendor/bacularis/bacularis-api -zxvf bacularis-api-$BACULARIS_VER.tar.gz
tar --strip-components 1 -C protected/vendor/bacularis/bacularis-web -zxvf bacularis-web-$BACULARIS_VER.tar.gz
# NOTE: this backslash in cp is intentional
\cp -rf protected/vendor/bacularis/bacularis-common/project/* ./
cp protected/vendor/npm-asset/fortawesome--fontawesome-free/css/all.min.css htdocs/themes/Baculum-v2/fonts/css/fontawesome-all.min.css
cp -r protected/vendor/npm-asset/fortawesome--fontawesome-free/webfonts/* htdocs/themes/Baculum-v2/fonts/webfonts/

Later you can remove the source archives:

# Remove source archives
rm -f bacularis-common-$BACULARIS_VER.tar.gz \
     bacularis-api-$BACULARIS_VER.tar.gz \
     bacularis-web-$BACULARIS_VER.tar.gz \
     bacularis-app-$BACULARIS_VER.tar.gz \
     bacularis-external-$BACULARIS_VER.tar.gz

Now you can start the upgrade. Here we assume that existing Bacularis is installed in a path /var/www/bacularis:

# NOTE: this backslash in cp is intentional
\cp -r /tmp/bacularis-update/. /var/www/bacularis