Snipe-IT Asset Management Installation Documentation

Welcome to the Snipe-IT documentation hub. You'll find comprehensive guides and documentation to help you install Snipe-IT as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Configuration

This section is where you edit the Snipe-IT configuration file to reflect your own settings, such as your database credentials, mail server, preferred language, timezone, and so on. Some of the settings are optional, some are required.

Don't be intimidated by the length of this page. The configuration options are pretty straightforward, we just like to explain what each of them do. :grinning:

Your Environmental Config File

🚧

IMPORTANT!

Snipe-IT caches these variables for you to speed things up. If you make subsequent changes to this file, make sure you run php artisan config:clear to clear the compiled version to see your changes.

All system configuration variables are stored in a single .env file in your project's root. To get started, copy over the .env.example file to a new .env file:

cp .env.example .env

(Click here for information on renaming files that begin with a dot in Windows.)

When you first get started, your .env file looks like this:

# --------------------------------------------
# REQUIRED: BASIC APP SETTINGS
# --------------------------------------------
APP_ENV=production
APP_DEBUG=false
APP_KEY=ChangeMe
APP_URL=null
APP_TIMEZONE='UTC'
APP_LOCALE=en
MAX_RESULTS=500

# --------------------------------------------
# REQUIRED: DATABASE SETTINGS
# --------------------------------------------
DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=null
DB_USERNAME=null
DB_PASSWORD=null
DB_PREFIX=null
DB_DUMP_PATH='/usr/bin'

# --------------------------------------------
# OPTIONAL: SSL DATABASE SETTINGS
# --------------------------------------------
DB_SSL=false
DB_SSL_KEY_PATH=null
DB_SSL_CERT_PATH=null
DB_SSL_CA_PATH=null
DB_SSL_CIPHER=null


# --------------------------------------------
# REQUIRED: OUTGOING MAIL SERVER SETTINGS
# --------------------------------------------
MAIL_DRIVER=smtp
MAIL_HOST=MAIL-PROVIDER.EXAMPLE.COM
MAIL_PORT=587
MAIL_USERNAME=YOURUSERNAME
MAIL_PASSWORD=YOURPASSWORD
MAIL_ENCRYPTION=null
[email protected]
MAIL_FROM_NAME='Snipe-IT'
[email protected]
MAIL_REPLYTO_NAME='Snipe-IT'
MAIL_BACKUP_NOTIFICATION_ADDRESS=null

# --------------------------------------------
# REQUIRED: IMAGE LIBRARY
# This should be gd or imagick
# --------------------------------------------
IMAGE_LIB=gd


# --------------------------------------------
# OPTIONAL: SESSION SETTINGS
# --------------------------------------------
SESSION_LIFETIME=12000
EXPIRE_ON_CLOSE=false
ENCRYPT=false
COOKIE_NAME=snipeit_session
COOKIE_DOMAIN=null
SECURE_COOKIES=false

# --------------------------------------------
# OPTIONAL: SECURITY HEADER SETTINGS
# --------------------------------------------
APP_TRUSTED_PROXIES=192.168.1.1,10.0.0.1
ALLOW_IFRAMING=false
REFERRER_POLICY=same-origin
ENABLE_CSP=false
CORS_ALLOWED_ORIGINS=null

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


# --------------------------------------------
# OPTIONAL: AWS S3 SETTINGS
# --------------------------------------------
AWS_SECRET=null
AWS_KEY=null
AWS_REGION=null
AWS_BUCKET=null

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

# --------------------------------------------
# OPTIONAL: MISC
# --------------------------------------------
APP_LOG=single
APP_LOG_MAX_FILES=10
APP_LOG_LEVEL=debug
FILESYSTEM_DISK=local
GOOGLE_MAPS_API=null
BACKUP_ENV=true

We'll spend some time breaking down these options so you're clear on what should go where.

🚧

NOTE:

Make sure there are no trailing spaces after the values you add in your .env file, as that can sometimes cause unexpected results.

REQUIRED: Basic App Settings

The first part of your .env file covers basic application settings.

# --------------------------------------------
# REQUIRED: BASIC APP SETTINGS
# --------------------------------------------
APP_ENV=production
APP_DEBUG=false
APP_KEY=ChangeMe
APP_URL=null
APP_TIMEZONE='US/Pacific'
APP_LOCALE=en
MAX_RESULTS=500
SettingNotes
APP_ENVThis should always be set to production unless you are a developer who is editing code within snipe-IT.
APP_DEBUGSetting this to true will turn on debugging in your Snipe-IT installation. This can be very useful for debugging, but should NEVER be left to true in a production environment.
APP_KEYThis is a randomly generated key that your system will use to store encrypted data. It's best not to change this manually, but to run php artisan key:generate to create a new key that is the right length. (You'll complete this step after you Install Dependencies - See Step 5 in the installation overview.)

Make sure you keep a backup of this value somewhere safe (password manager, etc).
APP_URLThis is the url to your application, beginning with http:// or https:// (if you're running Snipe-IT over SSL). This should not have a trailing slash, and you should not have public in the URL.

Images and javascript will not load correctly if this is not set to EXACTLY the URL you access your Snipe-IT app from.
APP_TIMEZONESet this to be the timezone you wish your Snipe-IT installation to use. This should use a PHP-supported timezone, and should be enclosed in single quotes.
APP_LOCALESet this to reflect the two-letter or 5-letter abbreviation for the language you'd like to use for Snipe-IT. The default language is US English (en), however we have additional language translations available, thanks to a great community of people helping us translate Snipe-IT
MAX_RESULTSDefault is 500. This is to prevent server timeouts and memory issues when someone (usually a custom script) naively tries to request 100k items at one time. You can increase this limit by setting this value to a higher number. Otherwise you should use standard pagination using the offset parameter to get your complete data set.

❗️

IMPORTANT:

Make sure you keep a backup of your APP_KEY somewhere safe.

Setting a Language

If you wish to use one of the other available languages, simply replace the default value of locale from en to one of the values listed below.

LanguageValue
English (US)en
English (UK)en-GB
Afrikaansaf
Arabicar
Bulgarianbg
Chinese Simplifiedzh-CN
Chinese Traditionalzh-TW
Croatianhr
Czechcs
Danishda
Dutchnl
Estonianet
Filipinofil
Finnishfi
Frenchfr
Germande
Greekel
Hebrewhe
Hungarianhu
Indonesianid
English, Indonesiaen-ID
Irishga-IE
Italianit
Japaneseja
Koreanko
Latvianlv
Lithuanianlt
Malayms
Maorimi
Mongolianmn
Norwegianno
Persianfa
Polishpl
Portuguesept-PT
Portuguese, Brazilianpt-BR
Romanianro
Russianru
Spanishes-ES
Spanish, Colombiaes-CO
Spanish, Mexicoes-MX
Spanish, Venezuelaes-VE
Swedishsv-SE
Tamilta
Turkishtr
Vietnamesevi
Zuluzu

If you're interested in additional languages, or would like to help us translate some of the incomplete existing languages, please see the Translations page. Check out the Snipe-IT CrowdIn translation project here to see current translation progress and all available languages.

REQUIRED: Database Settings

The next section in the .env asks you about your database settings:

# --------------------------------------------
# REQUIRED: DATABASE SETTINGS
# --------------------------------------------
DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=null
DB_USERNAME=null
DB_PASSWORD=null
DB_PREFIX=null
DB_DUMP_PATH='/usr/local/bin'

❗️

IMPORTANT:

You must create the database yourself if you did a manual installation (meaning you didn't use install.sh, or docker). Snipe-IT does not create the database or database users for you. Click here to learn more about creating a database and database user.

SettingNotes
DB_CONNECTIONLeave this as mysql. Snipe-IT currently only supports MySQL/MariaDB.
DB_HOSTThe host for your database. On most installations, you can leave this as localhost.
DB_DATABASEThe name of your Snipe-IT database.
DB_USERNAMEThe MySQL username you set up to access the database.
DB_PASSWORDYour database password for the user you specified above.
DB_PREFIXOnly required if you wish to use a prefix for your database tables. (Most installations can leave this set to null.)
DB_DUMP_PATHPath to the directory that contains mysqldump on your machine. This should point to the directory, not the binary itself.

This is often something like '/usr/bin' on linux systems.

Windows users should use something like: 'C:\\PROGRA~1\\MARIAD~1.0\\bin' or 'C:\\PROGRA~1\\MARIAD~1.1\\bin', depending your version (note the double-slashes).

If you're not sure what the path is to mysqldump, linux users can run which mysqldump and Windows users can use cmd /c for %A in ("C:\Program Files\MariaDB 10.1\bin") do @echo %~sA via command line to reveal the path information.
DB_SOCKETPath to the unix socket if you are connecting via socket instead. This field is optional and should only be used if you are connecting via socket.

REQUIRED: Outgoing Mail Settings

Outgoing mail settings are required in order for your Snipe-IT installation to send email. If you do not configure your mail settings, users will not be able to request a password reset if they get locked out, your email alerts for expiring licenses and assets (etc) will not work, and you cannot use asset acceptance/EULA requirements on your system.

# --------------------------------------------
# REQUIRED: OUTGOING MAIL SERVER SETTINGS
# --------------------------------------------
MAIL_DRIVER=smtp
MAIL_HOST=email-smtp.us-west-2.amazonaws.com
MAIL_PORT=587
MAIL_USERNAME=YOURUSERNAME
MAIL_PASSWORD=YOURPASSWORD
MAIL_ENCRYPTION=null
[email protected]
MAIL_FROM_NAME=Snipe-IT
[email protected]
MAIL_REPLYTO_NAME=Snipe-IT
MAIL_BACKUP_NOTIFICATION_ADDRESS=null

When you've completed the configuration setup and get to the Pre-Flight & Setup page, you will be able to test yout mail settings.

SettingNotes
MAIL_DRIVERSpecify the driver you would like to use. On most installations, you can leave this as smtp. Other options include mail to use the system's PHP mail function, or sendmail if you wish to use your server's sendmail.
MAIL_HOSTSpecify the hostname for your outgoing mail server. Keep in mind that this server must be accessible from the server you're running Snipe-IT on.
MAIL_PORTSet the port number that your mail server expects to send from. Some common port numbers are:

- 25 for unencrypted connections
- 587 for encrypted connections
MAIL_USERNAMESet the username of the authenticated user you'll be sending email as.
MAIL_PASSWORDSet the password for the authenticated user you'll be sending as.
MAIL_ENCRYPTIONHere you may specify the encryption protocol that should be used when the application sends e-mail messages. A sensible default using the transport layer security protocol should provide great security, however if your server doesn't support TLS or any other encryption (shame!), you can use null.
MAIL_FROM_ADDRSpecify an email address that is used globally for all e-mails that are sent by your application.
MAIL_FROM_NAMESpecify the name that should show up in the recipient's inbox when they receive email from your Snipe-IT instance.
MAIL_REPLYTO_ADDRSpecify the address that should be the reply:to on emails from your Snipe-IT instance. This can be the same as your MAIL_FROM_ADDR, but it is required.
MAIL_REPLYTO_NAMESpecify the name that should be the reply:to on emails from your Snipe-IT instance. This can be the same as your MAIL_REPLYTO_NAME , but it is required.
MAIL_BACKUP_NOTIFICATION_ADDRESSIf you would like email notifications to be sent out when backups fire, enter an email address here. Otherwise no backups will be sent.

GoDaddy Email

If you're using GoDaddy for hosting, you will need to set your mail server to use relay-hosting.secureserver.net on port 25, with username and password left as null values. See the GoDaddy relay server documentation for more specifics.

Using Gmail

If you're using Gmail to send your emails, you'll want to use the settings below (in addition to filling out the from address and name in the config file):

driversmtp
hostsmtp.gmail.com
port587
encryptiontls
usernameyour_gmail_username
passwordyour_gmail_password

Additionally, you may need to tweak a few settings in your Gmail account to handle Google's security that can kick in if Google doesn't recognize the system you're trying to access it through.

  • Sign into the Gmail account in a browser
  • Go here and enable access for "less secure" apps:
  • Then go here and click Continue.
  • If you're still getting errors, try this solution on StackOverflow.

(More info on sending email through Laravel and Gmail is available here, and more info on why Google makes you jump through these hoops is available here.)

If you're still having problems

If you don’t have easy access to a mail server (or you can't get your settings to work for some reason), we suggest signing up for Mandrill.

REQUIRED: Image Library Settings

GD Library or Imagemagick are required to generate barcodes for Snipe-IT, and to resize uploaded images associated with assets, asset models, etc. Specify which one you have available on your server.

# --------------------------------------------
# REQUIRED: IMAGE LIBRARY
# This should be gd or imagick
# --------------------------------------------
IMAGE_LIB=gd

OPTIONAL: Session Settings

These settings can usually be left as their defaults, however we'll walk through what each of the options do.

# --------------------------------------------
# OPTIONAL: SESSION SETTINGS
# --------------------------------------------
SESSION_LIFETIME=12000
EXPIRE_ON_CLOSE=false
ENCRYPT=false
COOKIE_NAME=snipeit_session
COOKIE_DOMAIN=null
SECURE_COOKIES=false
SettingNotes
SESSION_LIFETIMESpecify the time in seconds that the session should remain valid.
EXPIRE_ON_CLOSESpecify whether or not the logged in session should be expired when the user closes their browser window.
ENCRYPTSpecify whether you wish to use encrypted cookies for your Snipe-IT sessions.
COOKIE_NAMEUnless you're running multiple instances of Snipe-IT, you should be able to leave this as the default. If you are running multiple Snipe-IT installs, you should probably set this to a unique name for each one so that your browser doesn't get sessions confused.
COOKIE_DOMAINSpecify what domain name Snipe-IT should honor cookies from. This provides enhanced security, and should be set to whatever the domain name is of your Snipe-IT installation if you choose to use it. If you are having problems logging into your Snipe-IT instance, check and make sure this setting is correct.
SECURE_COOKIESBy setting this option to true, session cookies will only be sent back to the server if the browser has a HTTPS connection. This will keep the cookie from being sent to you if it can not be done securely. If you are not running your Snipe-IT over SSL, you should leave this as false.

❗️

IMPORTANT:

If you are NOT running Snipe-IT over SSL and you enable SECURE_COOKIES, your users will not be able to login to the site. Only use this option if you are running Snipe-IT over SSL.

Optional: Security Header Settings

# --------------------------------------------
# OPTIONAL: SECURITY HEADER SETTINGS
# --------------------------------------------
APP_TRUSTED_PROXIES=192.168.1.1,10.0.0.1
ALLOW_IFRAMING=false
REFERRER_POLICY=same-origin
ENABLE_CSP=false
CORS_ALLOWED_ORIGINS=null
SettingDefault ValueNotes
APP_TRUSTED_PROXIES192.168.1.1,10.0.0.1Enter your host IP address if you use a reverse proxy.
ALLOW_IFRAMINGfalseSet this to true if you need to run Snipe-IT within an iframe. This is an uncommon scenario, so you can leave this out or set it to false in most cases.
REFERRER_POLICYsame-origin
ENABLE_CSPfalseSet to true if you wish to enable the Content-Security-Policies for Snipe-IT.
CORS_ALLOWED_ORIGINSnullThis would only be used if you are building an external application that consumes the Snipe-IT API via client-side javascript. You must whitelist the FULLY QUALIFIED domains (including http:// or https:// protocol) here. Separate multiple domains with a comma, no spaces, and make sure the entire string is enclosed in quotes. Example:

CORS_ALLOWED_ORIGINS='https://snipeitapp.com,https://snipe.net,https://myawesomeapp.com'

❗️

WARNING

If you are consuming the Snipe-IT API through a custom front-end client-side application, make sure you do not expose your Bearer tokens in the front-end script.

Optional: Login Throttling

Snipe-IT utilizes brute force prevention to prevent attackers from attempting to brute-force logins to your installation. There is no way to disable brute force detection, but you can configure the maximum allowed attempts and the duration a user is locked out when they exceed that number.

SettingDefault ValueNotes
LOGIN_MAX_ATTEMPTS5The maximum number of failed attempts allowed before the user is throttled.
LOGIN_LOCKOUT_DURATION60The duration (in seconds) that the user should be blocked from attempting to authenticate again.

Optional: Misc

SettingDefault ValueNotes
APP_LOGsingleWhether to use a single log file, or multiple date-based log files for your app error logs. Set to daily for logs broken down into daily files.
APP_LOG_MAX_FILES10Max number of daily app log files to retain.
APP_LOG_LEVELdebugPossible levels are: "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"
FILESYSTEM_DISKlocalSnipe-IT only supports local disks at this time, so this setting should be left isn is.
APP_CIPHERAES-256-CBCYou should not change this unless you know what you're doing.
GOOGLE_MAPS_APIInclude your Google Maps API key here if you'd like Snipe-IT to load maps from Google on your locations and suppliers pages. For more information on setting this up, see our common issues.
BACKUP_ENVtrueSet this to true if you wish to backup your .env file in your Admin > Backups process. Set it to false to disable backing up .env files.

REQUIRED: Set Directory Permissions

You’ll need to make sure that the storage directory and its subdirectories, as well as the uploads directory within public are writable by your web server, since caches, log files, and uploaded files get written there.

The easiest way to handle permissions is to have your non-privileged user that owns your snipe-it project root set as belonging to the same group that the web server runs as.

useradd -g apache snipeit

The above creates a new linux user snipeit and adds them to the apache group. This is just an example though, and if you have experience running web servers, you probably already know how to manage this.

For more info on linux users and groups, click here.

You should use the minimum permissions available for writing, based on how you’ve got your web server configured.

chown -R snipeit storage public/uploads

Next, you'll want to ensure that this user has write permissions to those directories.

On Linux/OS X, you would do something like this:

chmod -R 755 storage
chmod -R 755 public/uploads

For help fixing permissions on IIS, see the Windows/IIS Installation Guide.

If you still run into a permissions error, you may need to increase the permissions to 775, or twiddle your user/group permissions on your server so that the web server (Apache, IIS, etc) can write to those directories.

❗️

IMPORTANT:

Make sure the Snipe-IT project directory is not owned by root. Your webserver should be running as your webserver’s user (often apache, nobody, or www-data). But never, ever root. Ever.

OPTIONAL: Set Your .htaccess to Redirect to SSL

If you are running Snipe-IT over HTTPS and wish to automatically redirect the user to the HTTPS version if they accidentally go to the HTTP version, uncomment the following lines from the public/.htaccess file:

RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

❗️

IMPORTANT:

If you are NOT running Snipe-IT over SSL and you enable this feature, your users will not be able to access the site. Only use this option if you are running Snipe-IT over SSL.

Updated about a month ago


Configuration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.