Upgrading to v4 from v3

Snipe-IT v4 includes a ton of new features and bug fixes, and all users are strongly encouraged to upgrade. For a full list of what's new in V4, click here.

Please note that Snipe-IT v4 does require PHP >= 5.6.4. Please see the list of requirements before upgrading.

❗️

Known Issues

Users running MariaDB 10.2.7 and later may have an issue upgrading or installing, due to a change in the way MariaDB stores null defaults. This issue will be fixed once the open pull request in the Doctrine repo is merged and a new version of Doctrine is released with these fixes. You can read more about that issue here.

Updating Snipe-IT should normally be pretty straightforward, but the upgrade to v4.0 from earlier versions requires a few extra steps, since we upgraded the core framework (Laravel) on which Snipe-IT is built, and some things changed inside of Laravel that we have had to change as a result.

This means that your initial upgrade to v4 will be a little more work than usual (boo!), but upgrades after v4.0 should be much easier than they used to be (yay!).

🚧

NOTE:

You should not have to make any web server changes or direct database changes to handle this upgrade. All of those settings should stay exactly as they are. You're simply swapping out files and running a few commands.

Please follow these steps in order, as some steps rely on previous steps having been completed before they can finish correctly.

*Please make sure you've checked the requirements page before attempting this upgrade.

Step 1: Backup your database

While logged in, go to Admin > Backups and generate a new backup. Download that file and keep it somewhere safe, in case you need to restore back to that version if something goes wrong with your upgrade.

❗️

Always backup your database before upgrading, not just this time

We try very hard to make sure that all database changes are non-destructive, but you should always backup beforehand anyway. You will never regret backing up your database. You may regret not doing so, so it’s just better to get into the habit.

Step 2: Backup your old version

The easiest way to do this will be to just copy the existing Snipe-IT into a temporary directory, but you can handle this any way that works for you. For example:

Shell

cd <install-dir>
cd ../
mkdir snipe-it-bkup
cp -R /var/www/snipe-it/ /var/www/snipe-it-bkup

You could also just make a zip copy of the old one - whatever you feel works for you where you have a backup of your config settings, your uploaded files, etc.

❗️

ALWAYS have a backup of your APP_KEY

You can find this in app/config/production/app.php as key, or after v3.0 in your .env file as APP_KEY. Losing this app key could lock you out of your application.

Step 3. Put Snipe-IT into maintenance mode

This isn't critical, but if you have multiple people working on managing your assets, it prevents them from running into errors if they access the app in the middle of your upgrade. From your Snipe-IT install directory:

Shell

php artisan down

Step 4: Remove old cache files

Remove the following three files:

• bootstrap/cache/config.php
• bootstrap/cache/services.php
• bootstrap/cache/compiled.php

And then run:

Text

composer dump
php artisan cache:clear
php artisan view:clear
php artisan config:clear

Step 5: Download/clone the new release

Do this the same way you did when you originally set Snipe-IT up. If you used git clone, you can simply do a git pull to grab the latest from the master branch.

Step 6: Update dependencies

Whenever you pull down a new version, you should update the dependencies via Composer and dump the autoloader.

NOTE: Never run composer as a super-user or Administrator. Always run it as the user that owns the Snipe-IT files. Running composer as a super-user will break things in ways that will be difficult to debug later. Just don't do it.

Shell

php composer.phar install --no-dev --prefer-source
php composer.phar dump-autoload

If you have composer installed globally, you can just run:

Shell

composer install --no-dev --prefer-source
composer dump-autoload

(Developers should remove the --no-dev flag, so they have unit test frameworks and debugging tools.)

Step 7: Copy over any new .env settings

Open up your .env file in your Snipe-IT install directory, and add any missing .env variables listed in the configuration section, like APP_LOCALE=en. Most will have a sensible fallback if you don't add them, but it's best to add them. If it's easier, you can view the .env.example and add what's missing to your .env.

Step 8: Check permissions

Double-check that your storage directory and all sub-directories are writable by the web server. This is where your cache, log files, and API OAuth keys live, so it must be writable by whoever the webserver runs as.

Step 9: Migrate the database

Always run your database migrations on any upgrade, as this will make sure your database schema is up to date with what the new code expected.

Shell

php artisan migrate

Forgetting to run these commands can mean your DB might end up out of sync with the new files you just pulled, or you may have some funky cached autoloader values.

It’s a good idea to get into the habit of running these every time you pull anything new down. If there are no database changes to migrate, it won't hurt anything to run migrations anyway, you’ll just see "Nothing to migrate".

Step 10: Recrypt any encrypted fields

If you are upgrading from a 3.x version of Snipe-IT, your app key was generated using the (now deprecated) mcrypt library.

Snipe-IT 4.x defaults to using an OpenSSL cipher instead of mcrypt - which will cause no issues if you are installing for the first time, but if you're upgrading, you may get a cipher error.

❗️

You MUST make sure you've backed up your original APP_KEY.

The recrypter attempts to use mcrypt to decrypt any encrypted custom fields you have. If you do not run the recrypter and you change your APP_KEY, it will:

• make any encrypted fields undecryptable
• make your LDAP password undecryptable
• void all browser sessions

If this happens, do the following:

• Open your .env file and add a new field called LEGACY_APP_KEY= and add your v3.x Snipe-IT APP_KEY value there.
• Also in your .env, add LEGACY_CIPHER=rijndael-256
• run php artisan key:generate to generate a new, non-mcrypt APP_KEY
• run php artisan config:clear to clear your config cache
• run php artisan snipeit:legacy-recrypt to decrypt and re-encrypt any encrypted custom fields
• clear your browser cookies

If you get a "Whoops" error when you try to login or refresh your Snipe-IT page, you probably forgot to clear your browser cookies. That error happens because we now use a more secure encryption cipher to encrypt your data (including sessions), and clearing your browser should fix that.

Step 11: Bring your app out of maintenance mode

From your Snipe-IT install directory:

Shell

php artisan up

Step 12: Launch Snipe-IT in a browser

You should be all set now, so just go to your old Snipe-IT URL and make sure everything is working.

🚧

If you're using auto-incrementing tags

We've added a new setting to Admin > Asset Tags that lets you set the starting point for the incrementer. If your asset auto-incrementing is off when you upgrade, change this setting to whatever the next asset tag ID should be.

Step 13: (Optional) Set Next Auto-Increment

If you're using auto-incrementing on your assets, you'll need to set your next auto-increment value. Go to Settings > Asset Tags and set the auto-increment value to whatever your next auto-increment should be:

Troubleshooting

If you have any issues upgrading, check the Common Issues page for a fix. If you don’t see your issue listed there, open an issue on Github and we’ll try to get you sorted out. Be sure to provide the information outlined in the Getting Help section of this site so that we have the info we need to assist you.