How to Perform a Clean Install of Snipe-IT: Complete Step-by-Step Guide

Execute the snipeit.sh Bash installer from the grokability/snipe-it repository to automate operating system detection, LAMP stack configuration, database provisioning, and Laravel bootstrapping.

Snipe-IT is an open-source IT asset management system built on Laravel 12 designed to run on a standard LAMP (Linux, Apache, MySQL, PHP) or LEMP (Linux, Nginx, MySQL, PHP) stack. The repository provides an official installation script that performs a clean install idempotently, detecting your distribution and handling package dependencies, web server configuration, and application setup automatically.

Automated Installation Using snipeit.sh

The snipeit.sh script at the root of the grokability/snipe-it repository orchestrates the entire installation process. It is designed to be idempotent, checking for existing packages, users, and databases before creating them, making it safe to re-run on clean virtual machines.

Operating System Detection and Package Installation

The installer begins by inspecting /etc/*release files to identify your distribution (Ubuntu, Debian, Raspbian, CentOS, Rocky Linux, Alma Linux, or Amazon Linux) and sets a $distro variable that drives the rest of the workflow. In snipeit.sh lines 24-33, the script determines which package manager to use (apt, yum, or dnf).

The install_packages helper function (lines 28-61) then installs required system packages including apache2/httpd, PHP with necessary extensions, mariadb-server, git, unzip, and other build dependencies. This ensures the base LAMP requirements are satisfied before the application is deployed.

Web Server Configuration and Virtual Hosts

The create_virtualhost function (lines 63-76 in snipeit.sh) generates an Apache virtual host configuration pointing the document root to "$APP_PATH/public". On Ubuntu and Debian systems, it enables the site using a2ensite, while on CentOS-based distributions it drops the configuration into /etc/httpd/conf.d/. This step is critical for Laravel's public directory routing to function correctly.

Database and User Provisioning

The script automatically generates a secure random password and creates a MariaDB database named snipeit with a dedicated user snipeit_dbuser (lines 38-42). These credentials are later injected into the application's environment file. The installer handles all SQL commands required to set up the database engine, user grants, and authentication.

Source Code Deployment and Environment Setup

Snipe-IT is cloned from GitHub into /var/www/html/snipeit and the master branch is checked out (lines 42-48). The script then copies .env.example to .env and uses sed to substitute critical values including the timezone, database credentials, APP_URL, and APP_KEY placeholders (lines 49-60).

The .env.example file in the repository root serves as the template for all environment-specific configuration, including mail settings and S3 storage options that you may customize post-installation.

Composer Dependencies and Application Bootstrap

The installer downloads Composer securely, verifies its SHA-384 signature, and installs it globally via the install_composer function (lines 109-134). It then executes:

composer install --no-dev --prefer-source

This command (lines 71-78) installs all PHP dependencies into the vendor directory without development packages. Finally, the script generates the Laravel application key, runs database migrations, and adds the scheduler cron entry (lines 82-89).

Manual Configuration and Post-Installation Tasks

While snipeit.sh automates the deployment, understanding the manual steps allows for customization and troubleshooting.

Environment File Configuration

After installation, the .env file in the application root contains your database and application settings. A minimal production configuration looks like this:

APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
APP_URL=http://snipeit.example.com
APP_TIMEZONE=UTC
APP_LOCALE=en-US

DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=snipeit
DB_USERNAME=snipeit_dbuser
DB_PASSWORD=RandomGeneratedPassword

You can manually edit these values to change the timezone, locale, or database connection parameters without re-running the installer.

Laravel Artisan Commands

To manually regenerate the application key or clear caches after installation, switch to the dedicated application user and run Artisan commands:

# Switch to the application user

sudo -i -u snipeitapp

# Generate a new app key (if you ever need to rotate it)

php /var/www/html/snipeit/artisan key:generate --force

# Run pending migrations

php /var/www/html/snipeit/artisan migrate --force

# Clear cached configuration & views

php /var/www/html/snipeit/artisan config:clear
php /var/www/html/snipeit/artisan view:clear

Scheduler Cron Setup

The installer automatically adds a cron entry for the Laravel scheduler, which handles background tasks like sending notifications and generating reports. The entry added to /etc/cron.d/snipeit or the root crontab is:

* * * * * /usr/bin/php /var/www/html/snipeit/artisan schedule:run >> /dev/null 2>&1

This ensures scheduled tasks run every minute without requiring a dedicated worker process.

File Permissions and Security Hardening

The script creates a dedicated system user snipeitapp and adds it to the Apache group (lines 78-99). This user owns the application files, while the web server requires write access only to specific directories: storage/, public/uploads/, and bootstrap/cache/.

The final housekeeping steps (lines 88-101) tighten permissions on the storage directory and restart the Apache service. If the host supports SELinux or UFW firewall, the script optionally applies security contexts and opens port 80/443.

Docker Installation Alternative

For containerized deployments, the repository includes Docker configuration in docker/README.md. You can perform a clean install using the official image:

docker pull snipe/snipe-it
docker run -d \
  -e APP_URL=http://localhost \
  -e DB_HOST=your-db-host \
  -e DB_DATABASE=snipeit \
  -e DB_USERNAME=snipeit \
  -e DB_PASSWORD=yourpassword \
  -p 80:80 snipe/snipe-it

The docker-compose.yml file in the repository root provides a complete stack with MariaDB for local development or simple production deployments.

Summary

• Use snipeit.sh for automated, idempotent installation on Ubuntu, Debian, CentOS, Rocky, Alma, or Amazon Linux.
• Verify prerequisites: Apache/Nginx, PHP with extensions, MariaDB/MySQL, and Git must be available or installed via the script.
• Document root must point to the public/ directory for Laravel routing to function correctly.
• Database credentials are auto-generated and injected into .env, but can be customized manually.
• Run Artisan commands as the snipeitapp user to avoid permission conflicts with the web server.
• Docker provides a containerized alternative documented in docker/README.md.

Frequently Asked Questions

What operating systems are supported for a clean install of Snipe-IT?

The snipeit.sh installer supports Ubuntu, Debian, Raspbian, CentOS, Rocky Linux, Alma Linux, and Amazon Linux by detecting /etc/*release files and adjusting package manager commands accordingly. For other distributions, manual installation following the steps in snipeit.sh is required.

How do I configure the database connection during installation?

The installer automatically creates a MariaDB database named snipeit and user snipeit_dbuser with a randomly generated password, injecting these values into .env via sed. You can override the password by setting environment variables before running the script, or manually edit .env post-installation to point to external database servers.

Is the snipeit.sh installer safe to run multiple times?

Yes, the script is idempotent. It checks for existing packages, system users, databases, and virtual host configurations before creating them, as implemented in functions throughout lines 24-101. This makes it safe to re-run if the installation is interrupted or if you need to reapply configurations.

How do I set up SSL/HTTPS after the initial installation?

The snipeit.sh script configures standard HTTP virtual hosts. After installation, you should manually edit the Apache configuration files created in /etc/apache2/sites-available/ (Debian/Ubuntu) or /etc/httpd/conf.d/ (CentOS) to add SSL certificate paths, or use a tool like Certbot to automatically configure HTTPS and redirect HTTP traffic to HTTPS.

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