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

> Easily install Snipe-IT on Ubuntu with our complete setup guide. Follow step-by-step instructions to configure PHP, MariaDB, and the repository for a seamless asset management experience.

- Repository: [Grokability, Inc./snipe-it](https://github.com/grokability/snipe-it)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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:

```bash
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:

```bash
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:

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

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

```

This command reads the [`composer.json`](https://github.com/grokability/snipe-it/blob/main/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:

```bash
cp .env.example .env
nano .env

```

Set the following essential variables in your `.env` file:

```dotenv
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:

```bash
php artisan key:generate

```

## Step 5: Database Migration and Seeding

Run the migrations to create tables and seed initial data:

```bash
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:

```bash
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:

```nginx
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:

```bash
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`](https://github.com/grokability/snipe-it/blob/main/package.json) and compile:

```bash
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`](https://github.com/grokability/snipe-it/blob/main/install.sh)** script that automates many of these steps. Additionally, the [`docker/README.md`](https://github.com/grokability/snipe-it/blob/main/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`](https://github.com/grokability/snipe-it/blob/main/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`](https://github.com/grokability/snipe-it/blob/main/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`](https://github.com/grokability/snipe-it/blob/main/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`](https://github.com/grokability/snipe-it/blob/main/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:

```bash
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`](https://github.com/grokability/snipe-it/blob/main/routes/api.php) and use transformers from `app/Http/Transformers/` to format JSON responses.