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:

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

Noq update dependencies and dump the auto-loader.

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:

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.

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.

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.


Did this page help you?