How to Update Snipe-IT from Version X to Y: A Complete Upgrade Guide

Updating Snipe-IT requires pulling the new codebase, running Composer and NPM to rebuild dependencies and assets, and executing Laravel migrations to update the database schema, all orchestrated through the upgrade.php helper script.

Updating Snipe-IT, the open-source IT asset management platform maintained by Grokability, involves coordinating changes across three distinct architectural layers. Whether you are migrating between major versions or applying a security patch, the upgrade process leverages Laravel's migration system and Node.js build tools to ensure consistency. This guide walks through the exact steps required to update Snipe-IT from version X to Y based on the source code structure in grokability/snipe-it.

Pre-Upgrade Requirements and Safety Checks

Before modifying any files, you must verify system compatibility and create a full backup. The repository includes a dedicated helper script located at upgrade.php in the root directory that performs sanity checks for PHP version requirements (8.2+), required extensions, and database connectivity.

Always create a complete backup of your database and application files:

# Backup the database

mysqldump -u $DB_USER -p$DB_PASSWORD $DB_DATABASE > snipeit_backup_$(date +%F).sql

# Backup application files

tar czf snipeit_files_$(date +%F).tar.gz /path/to/snipe-it

Run the pre-flight check to validate your environment can handle the target version:

php upgrade.php --check

The Three Layers of a Snipe-IT Upgrade

A complete update touches the application code, database structure, and front-end assets. Understanding these layers ensures you do not skip critical steps.

Application Code Layer

The PHP codebase updates via composer.json, which defines Laravel and third-party package dependencies. When you pull a new version tag, you must run Composer to install the updated packages and regenerate the autoloader:

composer install --no-interaction --prefer-dist --optimize-autoloader

This command reads the dependency tree from composer.json and ensures the PHP layer matches the target version's requirements.

Database Schema Layer

Snipe-IT stores all structural changes as Laravel migration files in database/migrations/. New versions may add tables, columns, or indexes. The php artisan migrate command applies only the migration files that have not yet run on your database:

php artisan migrate --force

The --force flag is essential for production environments to bypass the confirmation prompt.

Front-End Assets Layer

The UI relies on JavaScript and CSS compiled through Laravel Mix, configured in webpack.mix.js. After updating the PHP code, you must rebuild assets to incorporate any new interface components or styling changes:

# Install JavaScript dependencies

npm install

# Production build (minified)

npm run prod

# Or development build with source maps

npm run dev

Step-by-Step Upgrade Process

Follow this exact sequence to update from your current version to the target version:

1. Verify prerequisites using php upgrade.php --check
2. Pull the new code from the Git repository
3. Update PHP dependencies via Composer
4. Compile front-end assets using NPM
5. Apply database migrations with Artisan
6. Clear and rebuild caches to optimize performance
7. Verify the version in config/version.php

Execute these commands in order:

# Step 1: Check system compatibility

php upgrade.php --check

# Step 2: Fetch and checkout the target version (example: v6.5.0)

git fetch --tags
git checkout v6.5.0

# Step 3: Install updated PHP packages

composer install --no-interaction --prefer-dist --optimize-autoloader

# Step 4: Rebuild front-end assets

npm install
npm run prod

# Step 5: Apply database migrations

php artisan migrate --force

# Step 6: Clear and optimize caches

php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Step 7: Restart queue workers (if applicable)

php artisan queue:restart

The config/version.php file updates automatically upon successful completion, storing the current Snipe-IT version string for the application to reference.

Docker-Specific Considerations

If you run Snipe-IT using the provided docker-compose.yml, execute the same logical steps within the containers:

# Example Docker commands

docker-compose exec app php upgrade.php --check
docker-compose exec app git checkout v6.5.0
docker-compose exec app composer install --no-interaction --prefer-dist --optimize-autoloader
docker-compose exec app npm run prod
docker-compose exec app php artisan migrate --force

You may need to rebuild your Docker images if the underlying PHP version or system libraries changed between versions.

Summary

• Always backup your database and files before starting the upgrade process.
• Use upgrade.php to validate PHP version and extension requirements before pulling new code.
• Update in three layers: Application code via Composer, database schema via Artisan migrations, and front-end assets via NPM.
• Clear caches after upgrading to ensure the application recognizes new configuration and route changes.
• Verify success by checking config/version.php and testing core functionality like asset creation and reporting.

Frequently Asked Questions

Can I upgrade Snipe-IT directly from v5 to v6, or do I need intermediate steps?

You can typically upgrade directly between consecutive major versions, but you should always consult the README.md file in the target release for specific upgrade notes. Major version jumps may require intermediate steps if database migration paths are not maintained across multiple major releases. Running php artisan migrate --force will apply all pending migrations sequentially, but testing in a staging environment is critical for major upgrades.

What happens if a database migration fails during the upgrade?

If a migration fails, Laravel rolls back the specific migration batch that was running, leaving your database in the state it was before that batch began. Check the error output in your logs, fix the underlying issue (often a missing column or permission problem), and re-run php artisan migrate --force. The migrations in database/migrations/ are designed to be idempotent and safe to retry once the blocking issue is resolved.

Do I need to rebuild front-end assets for every update?

Yes, you should run npm run prod (or dev for testing) whenever you update the codebase. Even if the PHP backend updates successfully, the browser serves cached JavaScript and CSS from public/ directories. Without recompiling via the webpack.mix.js configuration, users will see a mismatched interface or encounter JavaScript errors when interacting with new API endpoints introduced in the updated version.

How do I verify the current Snipe-IT version after upgrading?

Check the config/version.php file, which contains the canonical version string for the running application. You can also run php artisan --version or view the version displayed in the Snipe-IT web interface footer. If the version file does not match your target tag, the git checkout or file replacement step may have failed, or you may need to clear the configuration cache using php artisan config:clear.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}