Installation Guide

Installation Methods

Snipe-IT can be installed using several methods. Choose the one that best fits your environment:

Docker

Recommended - Easiest setup and maintenance

Manual Installation

Full control - Ubuntu, Debian, CentOS, RHEL

Shared Hosting

cPanel, Plesk, and other shared hosts

Cloud Platforms

AWS, Azure, DigitalOcean, etc.

System Requirements

Before installing, ensure your system meets these requirements:

PHP Requirements

Snipe-IT requires PHP 8.2 or later. The application is built on Laravel 11.

Required PHP Extensions:

php-curl - cURL support
php-fileinfo - File information
php-gd or php-imagick - Image processing
php-iconv - Character encoding conversion
php-json - JSON support
php-mbstring - Multibyte string support
php-mysql or php-pgsql - Database driver
php-pdo - PDO database support
php-xml - XML support
php-zip - ZIP archive support
php-bcmath - Precision math

Optional Extensions:

php-ldap - LDAP/Active Directory integration
php-redis - Redis caching support
php-memcached - Memcached support

Database Requirements

Snipe-IT supports the following databases:

MySQL 5.7 or later
MariaDB 10.2 or later
PostgreSQL 9.6 or later (experimental)

Web Server

Apache 2.4+ with mod_rewrite enabled
Nginx 1.18+ with PHP-FPM

System Resources

Minimum Requirements:

1 CPU core
2GB RAM
5GB disk space

Recommended for Production:

2+ CPU cores
4GB+ RAM
20GB+ disk space (depending on uploads)

Docker Installation

Docker is the recommended installation method for most users. It provides isolation, easy updates, and consistent environments.

Using Docker Compose (Recommended)

Install Docker

Install Docker and Docker Compose on your system:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Desktop
brew install --cask docker

# Or download from:
# https://www.docker.com/products/docker-desktop

Create Project Structure

Create a directory for Snipe-IT:

mkdir -p /opt/snipe-it
cd /opt/snipe-it

Create docker-compose.yml

Create the Docker Compose configuration:

docker-compose.yml

volumes:
  db_data:
  storage:

services:
  app:
    image: snipe/snipe-it:latest
    restart: unless-stopped
    volumes:
      - storage:/var/lib/snipeit
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      db:
        condition: service_healthy
        restart: true
    env_file:
      - .env

  db:
    image: mariadb:11.4.7
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_DATABASE: ${DB_DATABASE}
      MYSQL_USER: ${DB_USERNAME}
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 1s
      retries: 5

Configure Environment Variables

Create your .env configuration file. Below are the key settings:

.env

# --------------------------------------------
# REQUIRED: BASIC APP SETTINGS
# --------------------------------------------
APP_ENV=production
APP_DEBUG=false
APP_KEY=
APP_URL=https://assets.yourcompany.com
APP_TIMEZONE=America/New_York
APP_LOCALE=en-US
MAX_RESULTS=500

# --------------------------------------------
# REQUIRED: DATABASE SETTINGS
# --------------------------------------------
DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=snipeit
DB_USERNAME=snipeit
DB_PASSWORD=CHANGE_ME_SECURE_PASSWORD
MYSQL_ROOT_PASSWORD=CHANGE_ME_ROOT_PASSWORD
DB_PREFIX=
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

# --------------------------------------------
# REQUIRED: FILE STORAGE SETTINGS
# --------------------------------------------
PRIVATE_FILESYSTEM_DISK=local
PUBLIC_FILESYSTEM_DISK=local_public

# --------------------------------------------
# REQUIRED: MAIL SERVER SETTINGS
# --------------------------------------------
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_FROM_ADDR=noreply@yourcompany.com
MAIL_FROM_NAME='Snipe-IT Asset Management'
MAIL_REPLYTO_ADDR=it-support@yourcompany.com
MAIL_REPLYTO_NAME='IT Support'
MAIL_TLS_VERIFY_PEER=true

# --------------------------------------------
# REQUIRED: IMAGE LIBRARY
# --------------------------------------------
IMAGE_LIB=gd

# --------------------------------------------
# OPTIONAL: SESSION SETTINGS
# --------------------------------------------
SESSION_DRIVER=file
SESSION_LIFETIME=12000
COOKIE_NAME=snipeit_session
SECURE_COOKIES=true

# --------------------------------------------
# OPTIONAL: CACHE SETTINGS
# --------------------------------------------
CACHE_DRIVER=file
QUEUE_DRIVER=sync

# --------------------------------------------
# OPTIONAL: SECURITY SETTINGS
# --------------------------------------------
APP_FORCE_TLS=true
ENABLE_CSP=true
ENABLE_HSTS=true
REFERRER_POLICY=same-origin
ALLOW_IFRAMING=false

# --------------------------------------------
# OPTIONAL: LOGIN THROTTLING
# --------------------------------------------
LOGIN_MAX_ATTEMPTS=5
LOGIN_LOCKOUT_DURATION=60

# --------------------------------------------
# OPTIONAL: API SETTINGS
# --------------------------------------------
API_THROTTLE_PER_MINUTE=120
API_TOKEN_EXPIRATION_YEARS=15

# --------------------------------------------
# OPTIONAL: BACKUP SETTINGS
# --------------------------------------------
BACKUP_ENV=true
ALLOW_BACKUP_DELETE=false

Security Notice:

Change all default passwords
Generate a secure APP_KEY (done automatically in next step)
Use HTTPS in production (APP_FORCE_TLS=true)
Enable security headers for production

Start the Application

Launch the containers:

docker-compose up -d

Generate Application Key

Generate the encryption key:

docker-compose exec app php artisan key:generate

Complete Web Setup

Access your Snipe-IT instance at http://your-server-ip and complete the setup wizard.

Using Pre-built Docker Image

Run Snipe-IT with a single command:

docker run -d \
  --name snipe-it \
  -p 80:80 \
  -e APP_ENV=production \
  -e APP_DEBUG=false \
  -e APP_KEY=<your-generated-key> \
  -e APP_URL=http://localhost \
  -e DB_HOST=db.yourserver.com \
  -e DB_DATABASE=snipeit \
  -e DB_USERNAME=snipeit \
  -e DB_PASSWORD=yourpassword \
  -v snipeit-storage:/var/lib/snipeit \
  snipe/snipe-it:latest

Manual Installation

Manual installation requires more system administration knowledge. Docker is recommended for most users.

Ubuntu 24.04 / Debian 12

Update System

sudo apt-get update
sudo apt-get upgrade -y

Install PHP 8.3 and Extensions

sudo apt-get install -y \
  php8.3 \
  php8.3-cli \
  php8.3-fpm \
  php8.3-mysql \
  php8.3-curl \
  php8.3-gd \
  php8.3-ldap \
  php8.3-mbstring \
  php8.3-xml \
  php8.3-zip \
  php8.3-bcmath \
  php8.3-redis

Install MySQL/MariaDB

# Install MariaDB
sudo apt-get install -y mariadb-server mariadb-client

# Secure installation
sudo mysql_secure_installation

# Create database and user
sudo mysql -e "CREATE DATABASE snipeit CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'snipeit'@'localhost' IDENTIFIED BY 'YourSecurePassword';"
sudo mysql -e "GRANT ALL PRIVILEGES ON snipeit.* TO 'snipeit'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

Install Apache

sudo apt-get install -y apache2 libapache2-mod-php8.3

# Enable required modules
sudo a2enmod rewrite
sudo a2enmod ssl
sudo systemctl restart apache2

Install Composer

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

Download Snipe-IT

cd /var/www
sudo git clone https://github.com/grokability/snipe-it snipe-it
cd snipe-it
sudo git checkout master

Install Dependencies

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

Configure Permissions

sudo chown -R www-data:www-data /var/www/snipe-it
sudo chmod -R 755 /var/www/snipe-it/storage
sudo chmod -R 755 /var/www/snipe-it/public/uploads

Configure Environment

sudo cp /var/www/snipe-it/.env.example /var/www/snipe-it/.env
sudo nano /var/www/snipe-it/.env

Update the database settings:

DB_HOST=localhost
DB_DATABASE=snipeit
DB_USERNAME=snipeit
DB_PASSWORD=YourSecurePassword

Generate Application Key

sudo php artisan key:generate

Configure Apache Virtual Host

Create /etc/apache2/sites-available/snipe-it.conf:

<VirtualHost *:80>
    ServerName assets.yourcompany.com
    DocumentRoot /var/www/snipe-it/public

    <Directory /var/www/snipe-it/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/snipeit_error.log
    CustomLog ${APACHE_LOG_DIR}/snipeit_access.log combined
</VirtualHost>

Enable the site:

sudo a2ensite snipe-it
sudo a2dissite 000-default
sudo systemctl reload apache2

Complete Web Setup

Navigate to http://your-server-ip and complete the setup wizard.

CentOS/RHEL 9

Enable EPEL and Remi Repositories

sudo dnf install -y epel-release
sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm
sudo dnf module reset php
sudo dnf module enable php:remi-8.3

Install PHP and Extensions

sudo dnf install -y \
  php \
  php-cli \
  php-fpm \
  php-mysqlnd \
  php-curl \
  php-gd \
  php-ldap \
  php-mbstring \
  php-xml \
  php-zip \
  php-bcmath \
  php-json

Install and Configure MariaDB

sudo dnf install -y mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb
sudo mysql_secure_installation

Install Apache

sudo dnf install -y httpd
sudo systemctl start httpd
sudo systemctl enable httpd

# Configure firewall
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Follow Ubuntu Steps 5-11

Continue with steps 5-11 from the Ubuntu installation, adjusting paths and commands as needed for RHEL.

Shared Hosting Installation

For shared hosting environments (cPanel, Plesk, etc.):

Shared hosting has limitations. Ensure your host meets the PHP 8.2+ requirement and allows SSH access or provides Composer.

Create Database

Use your hosting control panel to create:

A MySQL database
A database user with all privileges

Upload Files

Download the latest release from GitHub and upload via FTP/SFTP to your hosting directory.

Configure .env File

Rename .env.example to .env and update database credentials.

Install Dependencies

If SSH access is available:

composer install --no-dev
php artisan key:generate

If no SSH access, use your host’s PHP selector to run composer commands.

Set Document Root

Point your domain’s document root to the public directory.

Cloud Platforms

AWS EC2

Snipe-IT can run on AWS EC2 instances:

Launch an Ubuntu 24.04 EC2 instance (t3.small or larger)
Configure security groups to allow HTTP/HTTPS
Follow the Ubuntu manual installation steps
Use RDS for MySQL (recommended for production)
Use S3 for file storage (configure in .env)

DigitalOcean

Create a Droplet with Ubuntu 24.04
Follow the Ubuntu installation steps
Use DigitalOcean Managed Databases for MySQL
Use Spaces for object storage

Azure

Create an Ubuntu VM
Configure Network Security Group for HTTP/HTTPS
Follow Ubuntu installation steps
Use Azure Database for MySQL
Use Azure Blob Storage for uploads

Environment Variables Reference

Here are the most important environment variables from /home/daytona/workspace/source/.env.example:1-240:

Application Settings

Variable	Default	Description
`APP_ENV`	`production`	Application environment
`APP_DEBUG`	`false`	Enable debug mode (never in production!)
`APP_KEY`	-	Encryption key (auto-generated)
`APP_URL`	`null`	Your application URL
`APP_TIMEZONE`	`UTC`	Application timezone
`APP_LOCALE`	`en-US`	Default language
`MAX_RESULTS`	`500`	Maximum API results per request

Database Settings

Variable	Default	Description
`DB_CONNECTION`	`mysql`	Database type (mysql/pgsql)
`DB_HOST`	`127.0.0.1`	Database host
`DB_PORT`	`3306`	Database port
`DB_DATABASE`	`null`	Database name
`DB_USERNAME`	`null`	Database username
`DB_PASSWORD`	`null`	Database password
`DB_CHARSET`	`utf8mb4`	Character set
`DB_COLLATION`	`utf8mb4_unicode_ci`	Collation

Mail Settings

Variable	Default	Description
`MAIL_MAILER`	`smtp`	Mail driver
`MAIL_HOST`	-	SMTP server hostname
`MAIL_PORT`	`587`	SMTP port
`MAIL_USERNAME`	-	SMTP username
`MAIL_PASSWORD`	-	SMTP password
`MAIL_FROM_ADDR`	-	From email address
`MAIL_FROM_NAME`	`Snipe-IT`	From name

Post-Installation Configuration

Set Up Scheduled Tasks

Snipe-IT requires a cron job for scheduled tasks (notifications, backups, etc.):

# Cron is automatically configured in the Docker image
# No action needed

# Add to crontab
sudo crontab -e -u www-data

# Add this line:
* * * * * /usr/bin/php /var/www/snipe-it/artisan schedule:run >> /dev/null 2>&1

Configure File Permissions

Ensure proper permissions for uploads and cache:

# For Apache
sudo chown -R www-data:www-data storage public/uploads
sudo chmod -R 755 storage public/uploads

# For Nginx
sudo chown -R nginx:nginx storage public/uploads
sudo chmod -R 755 storage public/uploads

Enable SSL/HTTPS

For production environments, always use HTTPS:

sudo apt-get install certbot python3-certbot-apache
sudo certbot --apache -d assets.yourcompany.com

# Mount SSL certificates
volumes:
  - ./ssl/cert.pem:/var/lib/snipeit/ssl/snipeit-ssl.crt
  - ./ssl/key.pem:/var/lib/snipeit/ssl/snipeit-ssl.key

Troubleshooting Common Issues

500 Internal Server Error

Causes:

Incorrect file permissions
Missing .env file
Invalid APP_KEY

Solutions:

# Check permissions
sudo chown -R www-data:www-data /var/www/snipe-it
sudo chmod -R 755 /var/www/snipe-it/storage

# Regenerate app key
php artisan key:generate

# Check Apache error logs
sudo tail -f /var/log/apache2/error.log

Database Connection Failed

Check:

Database server is running
Credentials in .env are correct
Database user has proper privileges
Firewall allows database connection

Test connection:

mysql -h DB_HOST -u DB_USERNAME -p

Upload Errors

Check:

Directory permissions
PHP upload limits

Fix PHP limits in php.ini:

upload_max_filesize = 100M
post_max_size = 100M
memory_limit = 256M
max_execution_time = 300

Email Not Sending

Verify:

SMTP credentials are correct
Firewall allows outbound SMTP
Mail server requires TLS

Test email:

php artisan snipeit:test-email youremail@example.com

Performance Optimization

Enable Caching

For production environments, use Redis or Memcached:

.env

CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Optimize Composer Autoloader

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

Configure OPcache

Add to php.ini:

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2

Next Steps

User Management

Set up users, groups, and permissions

Asset Categories

Create categories and custom fields

API Access

Generate API tokens for integrations

LDAP/SAML

Configure enterprise authentication

Backups

Set up automated backups

Customization

Customize branding and email templates

Getting Help

If you encounter issues:

Common Issues Guide - Known problems and solutions
Discord Community - Live help from community
GitHub Issues - Search existing issues
Official Documentation - Complete documentation

Before asking for help, search the GitHub issues (both open and closed) and the Discord server - your question may already be answered!

​Installation Methods

Docker

Manual Installation

Shared Hosting

Cloud Platforms

​System Requirements

​PHP Requirements

​Database Requirements

​Web Server

​System Resources

​Docker Installation

​Using Docker Compose (Recommended)

​Using Pre-built Docker Image

​Manual Installation

​Ubuntu 24.04 / Debian 12

​CentOS/RHEL 9

​Shared Hosting Installation

​Cloud Platforms

​AWS EC2

​DigitalOcean

​Azure

​Environment Variables Reference

​Application Settings

​Database Settings

​Mail Settings

​Post-Installation Configuration

​Set Up Scheduled Tasks

​Configure File Permissions

​Enable SSL/HTTPS

​Troubleshooting Common Issues

​Performance Optimization

​Enable Caching

​Optimize Composer Autoloader

​Configure OPcache

​Next Steps

User Management

Asset Categories

API Access

LDAP/SAML

Backups

Customization

​Getting Help

Installation Methods

System Requirements

PHP Requirements

Database Requirements

Web Server

System Resources

Docker Installation

Using Docker Compose (Recommended)

Using Pre-built Docker Image

Manual Installation

Ubuntu 24.04 / Debian 12

CentOS/RHEL 9

Shared Hosting Installation

Cloud Platforms

AWS EC2

DigitalOcean

Azure

Environment Variables Reference

Application Settings

Database Settings

Mail Settings

Post-Installation Configuration

Set Up Scheduled Tasks

Configure File Permissions

Enable SSL/HTTPS

Troubleshooting Common Issues

Performance Optimization

Enable Caching

Optimize Composer Autoloader

Configure OPcache

Next Steps

Getting Help