How to Install Snipe-IT on Ubuntu: Complete Setup Guide

To install Snipe-IT on Ubuntu, install PHP 8.2+ and MariaDB, clone the grokability/snipe-it repository, run composer install --no-dev --optimize-autoloader, configure the .env file, and execute php artisan migrate --seed to initialize the database.

Snipe-IT is a Laravel-based asset management application maintained by Grokability that requires PHP 8.2+ with a MySQL or PostgreSQL backend. When you install Snipe-IT on Ubuntu, you are deploying a classic Laravel structure where the app/ directory contains core logic, routes/ defines web and API endpoints, and the public/ folder serves as the web root. This guide provides the complete installation process using the source code from the official repository.

Prerequisites and System Requirements

Before installing Snipe-IT on Ubuntu 22.04 LTS, ensure your server meets the following requirements:

• PHP 8.2 or higher with extensions: mbstring, xml, bcmath, gd, json, curl, zip, sqlite3, mysql, and pgsql
• Database server: MariaDB, MySQL, or PostgreSQL
• Web server: Nginx or Apache
• Composer: PHP dependency manager
• Git: For cloning the repository
• Node.js and npm: Optional, only if compiling frontend assets

The repository structure follows standard Laravel conventions with configuration files in config/, Blade views in resources/, and controllers in app/Http/Controllers/.

Step 1: Install System Packages

Update your package index and install the required dependencies:

sudo apt update && sudo apt upgrade -y

sudo apt install -y \
    nginx \
    php8.2-fpm php8.2-cli php8.2-mbstring php8.2-xml php8.2-bcmath \
    php8.2-gd php8.2-json php8.2-curl php8.2-zip php8.2-sqlite3 \
    php8.2-mysql php8.2-pgsql \
    composer \
    unzip \
    git \
    mariadb-server

Step 2: Configure the Database

Secure your MariaDB installation and create a dedicated database:

sudo mysql_secure_installation

sudo mysql -u root -p <<SQL
CREATE DATABASE snipeit CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'snipeit'@'localhost' IDENTIFIED BY 'StrongPasswordHere';
GRANT ALL PRIVILEGES ON snipeit.* TO 'snipeit'@'localhost';
FLUSH PRIVILEGES;
SQL

Step 3: Clone the Repository and Install Dependencies

Clone the official repository and install PHP dependencies:

git clone https://github.com/grokability/snipe-it.git
cd snipe-it

composer install --no-dev --optimize-autoloader

This command reads the composer.json file located in the repository root and installs Laravel plus additional packages like Passport for API authentication.

Step 4: Environment Configuration

Copy the example environment file and configure your application settings:

cp .env.example .env
nano .env

Set the following essential variables in your .env file:

APP_NAME="Snipe-IT"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://snipeit.example.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=snipeit
DB_USERNAME=snipeit
DB_PASSWORD=StrongPasswordHere

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=mailuser
MAIL_PASSWORD=mailpass
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=notifications@example.com

Generate the application encryption key:

php artisan key:generate

Step 5: Database Migration and Seeding

Run the migrations to create tables and seed initial data:

php artisan migrate --seed

After completion, the terminal displays the default admin credentials (typically admin / password), which you should change immediately upon first login.

Step 6: Set Directory Permissions

Configure proper ownership for Laravel's storage and cache directories:

sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 755 storage bootstrap/cache

The storage/ directory handles logs and uploaded files, while bootstrap/cache/ stores optimized configuration files.

Step 7: Configure the Web Server

Configure Nginx to serve the application from the public/ directory:

server {
    listen 80;
    server_name snipeit.example.com;
    root /path/to/snipe-it/public;

    index index.php;
    charset utf-8;
    gzip on;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/snipeit /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Optional: Compile Frontend Assets

If you modify the frontend or need to rebuild assets, install Node.js dependencies defined in package.json and compile:

npm install && npm run prod

This processes the Bootstrap and AdminLTE assets located in resources/.

Alternative Installation Methods

For automated deployments, the repository includes an install.sh script that automates many of these steps. Additionally, the docker/README.md file contains instructions for containerized deployments using Docker.

Summary

• Install PHP 8.2+ and required extensions (mbstring, xml, bcmath, etc.) along with MariaDB or PostgreSQL.
• Clone the grokability/snipe-it repository and run composer install --no-dev --optimize-autoloader to install Laravel dependencies.
• Configure the .env file with database credentials and application URL, then run php artisan key:generate.
• Initialize the database with php artisan migrate --seed to create tables and set up the admin user.
• Set permissions on storage/ and bootstrap/cache/ to www-data (or your web server user).
• Point your web server to the public/ directory, not the project root.
• Access the application via your configured domain and change the default admin password immediately.

Frequently Asked Questions

What PHP version is required to install Snipe-IT on Ubuntu?

Snipe-IT requires PHP 8.2 or higher according to the composer.json in the repository. You must install php8.2-fpm or php8.2-cli along with extensions including mbstring, xml, bcmath, gd, curl, and database drivers for MySQL (php8.2-mysql) or PostgreSQL (php8.2-pgsql).

Can I use the automated installation script instead of manual setup?

Yes, the repository includes an install.sh script that automates package installation, database setup, and configuration. However, manual installation gives you finer control over security settings, directory paths, and web server configuration, which is recommended for production environments.

Why does the web server need to point to the public/ directory?

Snipe-IT follows Laravel's security model where only the public/ directory should be web-accessible. This prevents exposure of sensitive files like .env, composer.json, or the app/ directory containing business logic. Pointing your Nginx or Apache document root to snipe-it/public/ ensures proper routing through index.php while protecting backend code.

How do I verify the API is working after installation?

Test the REST API by querying the app/Http/Controllers/Api/ endpoints with a valid API token:

curl -H "Accept: application/json" \
     -H "Authorization: Bearer <API_TOKEN>" \
     https://snipeit.example.com/api/v1/hardware

The API routes are defined in routes/api.php and use transformers from app/Http/Transformers/ to format JSON responses.

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