Upgrading to v3

Updating Snipe-IT should normally be pretty straightforward, but the upgrade to v3.0 from earlier versions is a little different, 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 v3 will be a little more work than usual (boo!), but upgrades after v3.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 the files, and copying over your configuration settings into the new .env file.

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 rename your old Snipe-IT install directory and create a new, empty directory that uses the old directory name, but you can handle this any way that works for you.

For example, if your Snipe-IT was installed in /var/www/snipe-it, you could rename that directory to /var/www/snipe-it-backup and then create a new directory /var/www/snipe-it.

❗️

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: 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 should clone the repo again from scratch, since so many files have moved or been renamed.

Step 4: 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.

1st you'll need to install composer into the directory if you don't have it installed globally:

Shell

cd <install-dir>
curl -sS https://getcomposer.org/installer | php

Noq update dependencies and dump the auto-loader.

Shell

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

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

Step 5: Copy over your configuration settings

🚧

IMPORTANT:

This step will only need to be done once, while upgrading to v3.0. Once you've upgraded to v3.0, you won't ever have to do this part again.

Open up your .env file in your new Snipe-IT install directory, and update the configuration placeholders you see there with the values you were previously using in your individual config files.

If you don't have a .env file, just copy the existing .env.example over to .env and use that:

Shell

cp .env.example .env

The files you'll be copying from are:

• app/config/app.php
• app/config/production/app.php
• app/config/production/database.php
• app/config/production/mail.php
• app/config/production/session.php

New .env Setting	Old Config File	Old Config File Key	Notes
APP_ENV	N/A	N/A	Set to production
APP_DEBUG	/app/config/production/app.php	debug
APP_KEY	/app/config/production/app.php	key	Make SURE you keep this app key the same from your old version.
APP_URL	/app/config/production/app.php	url
APP_TIMEZONE	/app/config/app.php	timezone
APP_LOCALE	/app/config/app.php	locale
DB_CONNECTION	/app/config/production/database.php	default	This should be mysql
DB_HOST	/app/config/production/database.php	connections-> mysql-> host
DB_DATABASE	/app/config/production/database.php	connections-> mysql-> database
DB_USERNAME	/app/config/production/database.php	connections-> mysql-> username
DB_PASSWORD	/app/config/production/database.php	connections-> mysql-> password
DB_PREFIX	/app/config/production/database.php	connections-> mysql-> prefix
DB_DUMP_PATH	N/A	N/A	Path to your dabase dump binary (such as mysqldump) e.g. '/usr/local/bin'
MAIL_DRIVER	/app/config/production/mail.php	driver
MAIL_HOST	/app/config/production/mail.php	host
MAIL_PORT	/app/config/production/mail.php	port
MAIL_USERNAME	/app/config/production/mail.php	username
MAIL_PASSWORD	/app/config/production/mail.php	password
MAIL_ENCRYPTION	/app/config/production/mail.php	encryption
MAIL_FROM_ADDR	/app/config/production/mail.php	from->address
MAIL_FROM_NAME	/app/config/production/mail.php	from->name
IMAGE_LIB	N/A	N/A	Should be set to gd or imagick, depending on which library you have on your server.
SESSION_LIFETIME	/app/config/production/session.php	lifetime
EXPIRE_ON_CLOSE	/app/config/production/session.php	expire_on_close
ENCRYPT	N/A	N/A	Should be set to true if you wish to encrypt your cookies.
COOKIE_NAME	/app/config/production/session.php	cookie
COOKIE_DOMAIN	/app/config/production/session.php	domain
SECURE_COOKIES	/app/config/production/session.php	secure

Everything else in your .env can be left alone, as they are more advanced settings that are not commonly used.

Step 6: Move uploaded files and check permissions

Since Laravel's file structure has changed, you're going to need to move a few files around to make sure your uploaded files (logo, uploaded asset files, asset model files, etc) are in their new location.

Shell

cp ../snipe-it-backup/app/storage/dumps/* snipe-it/storage/app/backups/
cp ../snipe-it-backup/app/private_uploads/* snipe-it/storage/private_uploads/
cp ../snipe-it-backup/public/uploads/* snipe-it/public/uploads/

Also confirm that your entire storage directory (and subdirectories) is writable by the web server.

Step 7: 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 8: 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.

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.