diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..f3ab4a2a44 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,38 @@ +--- +currentMenu: home +--- + +# Snipe-IT Installation Guide + +Snipe-IT is a Free Open Source (FOSS) project for IT asset management, to enable IT departments to track who has which laptop, when it was purchased, which software licenses and accessories are available, and so on. + +It is built on [Laravel 4.2](http://laravel.com) and uses the [Sentry 2](https://github.com/cartalyst/sentry) package. + +This project is actively developed and we [release quite frequently](https://github.com/snipe/snipe-it/releases). __Check out the [Snipe-IT website](http://www.snipeitapp.com) for a demo, a comprehensive list of features, screenshots and [our blog](http://snipeitapp.com/news/) for updates on new versions.__ + +__This is web-based software__. This means there there is no executable file (aka no .exe files), and it must be run on a web server and accessed through a web browser. It runs on any flavor of Linux or OSX as well as Windows. + +----- + +
+ We + +
+ +----- + + + + +### Bug Reports & Feature Requests + +Feel free to check out the [GitHub Issues for this project](https://github.com/snipe/snipe-it/issues) to open a bug report or see what open issues you can help with. Please search through existing issues (open and closed) to see if your question hasn't already been answered before opening a new issue. + +We use Waffle.io to help better communicate our roadmap with users. Our [project page there](http://waffle.io/snipe/snipe-it) will show you the backlog, what's ready to be worked on, what's in progress, and what's completed. + +[![Stories in Ready](https://badge.waffle.io/snipe/snipe-it.png?label=ready+for+dev&title=Ready+for+development)](http://waffle.io/snipe/snipe-it) + +----- +### Announcement List + +To be notified of important news (such as new releases, security advisories, etc), [sign up for our list](http://eepurl.com/XyZKz). We'll never sell or give away your info, and we'll only email you when it's important. diff --git a/docs/common-issues.md b/docs/common-issues.md new file mode 100644 index 0000000000..3dea81b4a1 --- /dev/null +++ b/docs/common-issues.md @@ -0,0 +1,176 @@ +--- +currentMenu: common-issues +--- + +# Common Issues + +
+ +While installation should be pretty simple, here are some of the more common questions/issues people have. + +----- + +## The requested URL /auth/signin was not found on this server +Chances are that `mod_rewrite` is either not installed on your system, or has not been configured correctly for your virtualhost using AllowOverride. + +__Troubleshooting:__ +Add garbage text into the `public/.htaccess` file on your local install and hit the homepage again. If it bombs out (it should), then mod_rewrite is probably working. If it doesn't, it means your webserver isn't even looking for the .htaccess rules and you'll need to check your virtualhost config. + +(Make sure to take the garbage out of the .htaccess file once you've gotten it sorted!) + +----- + +## PHP Warning: require(/var/www/html/snipeit/bootstrap/../vendor/autoload.php): failed to open stream: No such file or directory + +When you see this error, it means that you either forgot to install or run composer, or you did and it failed somewhere and didn't complete, so the dependencies Snipe-IT needs were not installed. See the docs on installing and running composer, and check for any errors composer might return when you attempt to run `composer install`. + +Once your composer errors are resolved, you can continue with the installation. + +----- + +## Error message: mcrypt_encrypt(): Size of key is too large for this algorithm + +In `app/config/production/app.php`, find the `key` on line 56. + +You can run + +``` +php artisan key:generate +``` + +to auto-generate a 32-character key for you. Paste the generated key in as the value of `key` in your config (within single quotes): + +``` +'key' => '36VpJ9xE3WyPQu4GYgckF82hRh9AVjYM', +``` + +----- + +## Error message: mcrypt_encrypt(): Key size not supported by this algorithm. Only keys of sizes 16, 24 or 32 supported. + +In `app/config/production/app.php`, find the `key` on line 56. + +You can run + +``` +php artisan key:generate +``` + +to auto-generate a 32-character key for you. Paste the generated key in as the value of `key` in your config (within single quotes): + +``` +'key' => '36VpJ9xE3WyPQu4GYgckF82hRh9AVjYM', +``` + +----- + +## During install or running migrations - SQLSTATE[HY000]: General error: 1005 Can't create table 'snipeit.#sql-3626_1c6' (errno: 150) + +This happens when your default table engine is set to MyISAM (which in general is weird. InnoDB has been the default table engine in MySQL for quite some time). + +If you see this error: + +``` +Illuminate\Database\QueryException] +SQLSTATE[HY000]: General error: 1005 Can't create table 'snipeit.#sql-3626_1c6' (errno: 150) (SQL: alter table users add constraint users_company +_id_foreign foreign key (company_id) references companies (id)) + +[PDOException] +SQLSTATE[HY000]: General error: 1005 Can't create table 'snipeit.#sql-3626_1c6' (errno: 150) +``` + +Try running: + +``` +ALTER TABLE companies ENGINE = InnoDB; +``` + +on your MySQL database and then re-run migrations. + +----- + +## Call to undefined function Controllers\Admin\ldap_connect() + +The PHP LDAP extension is not installed on your server. While this extension is not required for all Snipe-IT installations, it must be installed if you wish to use any of the LDAP functionality. + +----- + + +## White page with error: Error in exception handler. + +Make sure you've changed the permissions on the `app/storage` directory and all of the directories within to be writable by the web server. + +----- + +## Database [] not configured + +This happens when you think you're running the app in a different environment than your app thinks it's running in. The most common reason for this is you either forgot to edit `bootstrap/start.php` to include your hostname in whichever environment you want to run it as, or the hostname you entered there is incorrect. +Snipe-IT will always default to production if it can't figure out what mode to run in. + +To find your hostname, type `hostname` in a terminal prompt and copy the output to whichever of the environments in `bootstrap/start.php` that you want to run it in. The app examines this array, and if it finds a hostname there that matches the actual hostname, that's the environment it will run in. + +Alternatively, you can try just copying your config files over into `app/config/production` and just letting it default to production if you don't plan on doing any code development. + +----- + +## FatalErrorException. Syntax error, unexpected '[', expecting ')' + +The version of PHP you're using is too old to run Snipe-IT, which [requires](requirements.html) PHP 5.4 or later. + +After upgrading PHP, you should also delete the contents of the cached views in `app/storage/views` once you upgrade PHP, to resolve any cached issues. + +----- + +## Error message: Error Output: PHP Fatal error: Call to undefined method IlluminateFoundationApplication::registerCoreContainerAliases() in ../src/Illuminate/Foundation/start.php on line 106 + +Remove `bootstrap/compiled.php` and your vendors dir, and try running `php composer.phar update`. + +----- + +## Image Source not readable + +This usually means that the temporary directory is not writable by the web server. Check the permissions section of the documentation for your server OS and make sure you've granted the user the ability to write to the temp directory. + +----- + +## While running composer: intervention/image dev-master requires ext-fileinfo * -> the requested PHP extension fileinfo is missing or not enabled on your system. + +As the error states, your server is missing the `fileinfo` extension, which is one of the requirements for running Snipe-IT. + +Windows users must include the bundled `php_fileinfo.dll `DLL file in `php.ini` to enable this extension. To enable Fileinfo, add or uncomment this line in your php.ini: + +``` +extension=php_fileinfo.dll +``` + +and restart the web server. + +Linux users need to add or uncomment the following in their `php.ini`: + +``` +extension=fileinfo.so +``` + +and restart the web server. + +----- + +## During composer install, it's asking me for my Github credentials + +This is an artifact of Github having a very low API rate limit for unauthenticated accounts. Make sure you're using the `--prefer-source` flag when doing your composer installs and updates. + +----- + +## Call to undefined method IlluminateCookieCookieJar::get() + +If you're using Snipe-IT 1.2.6 or earlier, grab the latest off of the develop branch and run `php composer install`, or edit your composer.json to use Sentry 2.1.* and then run `php composer update`. + +----- + +## PHP Fatal error: Class 'Patchwork\Utf8\Bootup' not found in \bootstrap\autoload.php on line 43 + +This happens sometimes with composer, though we don't really know why, as it's not specific to Snipe-IT. If you run into this error after running `php composer.phar install --no-dev --prefer-source`, try the following: + +- delete your `composer.lock` file +- run `php composer.phar dump-autoload` +- run `php composer.phar update --no-dev --prefer-source` diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000000..4cc11267bb --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,83 @@ +--- +currentMenu: contributing +--- + +# Contribution Guidelines + + +
+ +**Before opening an issue to report a bug or request help, make sure you've checked the [Common Issues](common-issues.html) and [Getting Help](getting-help.html) pages.** + +## Developing on Snipe-IT + +Please submit all pull requests to the [snipe/snipe-it](http://github.com/snipe/snipe-it) repository in the `develop` branch! + +**As you're working on bug-fixes or features, please break them out into their own feature branches and open the pull request against your feature branch**. It makes it _much_ easier to decipher down the road, as you open multiple pull requests over time, and makes it much easier for us to approve pull requests quickly. + +If you don't have a feature in mind, but would like to contribute back to the project, check out the [open issues](https://github.com/snipe/snipe-it/issues?state=open) and see if there are any you can tackle. + +If you have a feature in mind that hasn't been asked for in Github Issues, please open an issue so that we can discuss how it should work so that it will benefit the entire community. + +We use Waffle.io to help better communicate our roadmap with users. Our [project page there](http://waffle.io/snipe/snipe-it) will show you the backlog, what's ready to be worked on, what's in progress, and what's completed. Issues that have been approved by the project maintainer are labeled "ready for dev". + +[![Stories in Ready](https://badge.waffle.io/snipe/snipe-it.png?label=ready+for+dev&title=Ready+for+Development)](http://waffle.io/snipe/snipe-it) + +The labels we use in GitHub Issues and Waffle.io indicate also whether we've confirmed an issue as a bug, whether we're considering the issue as a potential feature, and whether it's ready for someone to work on it. We also provide labels such as "n00b", "intermediate" and "advanced" for the experience level we think it requires for contributors who want to help. + +----- + +## Setting Up a Dev Installation + +The only real difference in setting Snipe-IT up for local development versus setting it up for production usage is the configuration files, and remembering to add the local environment flag on the artisan commands. + +You’ll notice in your `app/config directory`, you have directories such as `local`, `staging`, and `production`. (The `testing` directory is reserved for unit tests, so don’t mess with that one.) + +You’ll want to make sure you have the configuration files updated for whichever environment you’re in, which will most likely be `local`. + +If your development, staging and production sites all run on the same server (which is generally a terrible idea), see [this example](http://words.weareloring.com/development/setting-up-multiple-environments-in-laravel-4-1/) of how to configure the app using environmental variables. + +If you run the command line tools without the local flag, it will default to the production environment, so you’ll want to make sure you run the commands as: + +``` +php artisan key:generate --env=local +php artisan app:install --env=local +``` + +----- + +## Set up the debugbar + +In dev mode, we use the fabulous [Laravel Debugbar](https://github.com/barryvdh/laravel-debugbar) by [barryvdh](https://github.com/barryvdh). + +The profiler is enabled by default if you have `debug` set to `true` in your `app.php`. You certainly don’t have to use it, but it’s pretty handy for troubleshooting queries, seeing how much memory your pages are using, making sure your code isn't introducing n+1 queries, etc. + +----- + +## Database Considerations + +Always make sure you're eager loading queries where possible, to avoid "N+1 query" issues with large data sets. The debugbar at the bottom of your development installation will show you the number of queries you're executing, which should alert you to any issues. + +----- + +## Purging the autoloader + +If you’re doing any development on this, make sure you purge the auto-loader if you see any errors stating the new model you created can’t be found, etc, otherwise your new models won’t be grokked. + +``` +php composer.phar dump-autoload +``` + +----- + +## Localization Support + +When developing on Snipe-IT, please always use language strings (`@lang('path/to/file.string')` in blades, `Lang::get('path/to/file.string')` in controllers) instead of regular text on any user-facing text, so that we can easily extend your changes out to the translation community. + +You do not need to provide translated strings for all of the languages we support, only English (`app/lang/en`). We use CrowdIn for translation management by native speakers, so you only need to provide English strings. More info on translations [available here](translations.html). + +----- + +## Contributor Code of Conduct + +Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. [See the source on Github](https://github.com/snipe/snipe-it) to read the current version of the Code of Conduct. diff --git a/docs/couscous.yml b/docs/couscous.yml new file mode 100644 index 0000000000..04106b93ab --- /dev/null +++ b/docs/couscous.yml @@ -0,0 +1,154 @@ +template: + # Name of the directory containing the website template (default is "website") + + directory: website + # Or if you are using a remote template, you can set the Git URL + #url: https://github.com/snipe/Template-ReadTheDocs.git + +# List of directories to exclude from the processing (default contains "vendor" and "website") +# Paths are relative to the repository root +exclude: + - vendor + - app + - public + - website + - public + - .DS_STORE + +# Any variable you put in this file is also available in the Twig layouts: +title: Snipe-IT Documentation + +# The left menu bar +menu: + sections: + introduction: + name: + items: + home: + text: Introduction + relativeUrl: index.html + requirements: + text: Requirements + relativeUrl: requirements.html + security: + text: Security + relativeUrl: security.html + + installation: + name: ' Installation' + items: + overview: + text: Overview + relativeUrl: installation/index.html + downloading: + text: 1. Downloading + relativeUrl: installation/downloading.html + configuration: + text: 2. Configuration + relativeUrl: installation/configuration.html + composer: + text: 3. Install Dependencies + relativeUrl: installation/composer.html + command-line: + text: 4. The CLI Installer + relativeUrl: installation/command-line.html + server: + text: 5. Server Configuration + relativeUrl: installation/server/index.html + linux-osx: + text: " Linux/OSX" + relativeUrl: installation/server/linux-osx.html + windows: + text: " Windows" + relativeUrl: installation/server/windows.html + wamp: + text: " WAMP" + relativeUrl: installation/server/wamp.html + xampp: + text: " XAMPP" + relativeUrl: installation/server/xampp.html + docker: + text: " Docker" + relativeUrl: installation/server/docker.html + subdirectory: + text: "Subdirectories" + relativeUrl: installation/subdirectory.html + proxy: + text: "Using a Reverse Proxy" + relativeUrl: installation/proxy.html + manually-editing-data: + text: "Manually Editing Data" + relativeUrl: installation/manually-editing-data.html + + upgrading: + text: Upgrading + relativeUrl: upgrading.html + contributing: + text: Contributing + relativeUrl: contributing.html + translations: + text: Translations + relativeUrl: translations.html + + help: + name: " Help" + items: + common-issues: + text: Common Issues + relativeUrl: common-issues.html + getting-help: + text: "Getting Help" + relativeUrl: getting-help.html + + + manual: + name: " User's Manual" + items: + manual-home: + text: Basic Concepts + relativeUrl: manual/index.html + user-management: + text: "LDAP / User Management" + relativeUrl: manual/user-management/index.html + importing-assets: + text: "Importing Assets" + relativeUrl: manual/importing-assets.html + importing-licenses: + text: "Importing Licenses" + relativeUrl: manual/importing-licenses.html + alerts: + text: "Configuring Alerts" + relativeUrl: manual/alerts.html + labels: + text: "Generating Labels" + relativeUrl: manual/labels.html + backups: + text: "Backups" + relativeUrl: manual/backups.html + custom-fields: + text: Custom Fields and Fieldsets + relativeUrl: manual/custom-fields.html + + + + misc: + name: + items: + license: + text: License + relativeUrl: license.html + website: + text: Main Website + absoluteUrl: http://snipeitapp.com + + + + +# Base URL of the published website (no "/" at the end!) +# You are advised to set and use this variable to write your links in the HTML layouts +baseUrl: http://docs.snipeitapp.com + +# Used to link to the GitHub project +github: + user: snipe + repo: snipe-it diff --git a/docs/developers/README.md b/docs/developers/README.md new file mode 100644 index 0000000000..245f5c0e4a --- /dev/null +++ b/docs/developers/README.md @@ -0,0 +1,41 @@ +# Developing & Contributing + +
+ +Please be sure to see the [contributing guidelines](https://github.com/snipe/snipe-it/blob/develop/CONTRIBUTING.md) before submitting pull requests. + +The only real difference in setting Snipe-IT up for local development versus setting it up for production usage is the configuration files, and remembering to add the local environment flag on the artisan commands. + +You'll notice in your `app/config` directory, you have directories such as `local`, `staging`, and `production`. (The `testing` directory is reserved for unit tests, so don't mess with that one.) + +You'll want to make sure you have the configuration files updated for whichever environment you're in, which will most likely be `local`. + +If you run the command line tools without the local flag, it will default to the production environment, so you'll want to make sure you run the commands as: + + php artisan key:generate --env=local + php artisan app:install --env=local + +### Set up the debugbar + +In dev mode, I use the fabulous [Laravel Debugbar](https://github.com/barryvdh/laravel-debugbar) by [barryvdh](https://github.com/barryvdh). After you've installed/updated composer, you'll need to publish the assets for the debugbar: + + php artisan debugbar:publish + +The profiler is enabled by default if you have debug set to true in your app.php. You certainly don't have to use it, but it's pretty handy for troubleshooting queries, seeing how much memory your pages are using, etc. + +----- + +### Purging the autoloader + +If you're doing any development on this, make sure you purge the auto-loader if you see any errors stating the new model you created can't be found, etc, otherwise your new models won't be grokked. + + php composer.phar dump-autoload + + +----- + +### Translations + +You do not need to provide translated strings for all of the languages we support, only English (`app/lang/en`). We use CrowdIn for translation management by native speakers, so you only need to provide English strings. More info on translation is [available here](../translations.html). + +----- diff --git a/docs/getting-help.md b/docs/getting-help.md new file mode 100644 index 0000000000..1294b4aa7e --- /dev/null +++ b/docs/getting-help.md @@ -0,0 +1,42 @@ +--- +currentMenu: getting-help +--- + +# Getting Help + +If you're having trouble setting up Snipe-IT, don't worry! + +__First__, check the [common issues page](common-issues.html) to make sure your problem hasn't already been addressed. We update that page frequently as requests come in. + +If you can't find your issue there, simply post a new issue in the [Github Issues for Snipe-IT](https://github.com/snipe/snipe-it/issues), or ask in the [Snipe-IT Gitter chat room](https://gitter.im/snipe/snipe-it?utm_source=share-link&utm_medium=link&utm_campaign=share-link) and we'll try to get you sorted out. + +Before posting an issue, please read the following so we can help you as quickly and efficiently as possible. + +### Enable debug mode + +In your `app/config/production/app.php`, set `debug` to true. You'll switch this back to false once we're done debugging your issue, but this will turn on verbose errors on the screen and will help you see what's breaking. + +__If you get an "Oops!" or "Whoops!" message in the browser when you hit a specific page, that means debug is set to `false`.__ Set it to `true`, and reload for detailed errors. + +### Enable your browser's error console + +Sometimes errors reported by your browser can lend clue as to what's going on. [Enable your browser's error console](http://webmasters.stackexchange.com/questions/8525/how-to-open-the-javascript-console-in-different-browsers) to see any client-side errors that may be causing issues. + +### Posting an issue to Github or Gitter +When posting a new issue, please be SURE to include the following: + +- Version of Snipe-IT you're running. (If you didn't grab an official release, let us know which branch you pulled from.) +- What OS and web server you're running Snipe-IT on +- What method you used to install Snipe-IT (`install.sh`, manual installation, docker, etc) +- If you're getting an error in your browser, include that error. +- What specific Snipe-IT page you're on, and what specific element you're interacting with to trigger the error +- If a stacktrace is provided in the error, include that too. +- Any errors that appear in your browser's error console. +- Confirm whether the error is reproduceable [on the demo](https://snipeitapp.com/demo). +- Include any additional information you can find in `app/storage/logs` and your webserver's logs. +- Include what you've done so far in the installation, and if you got any error messages along the way. +- Indicate whether or not you've manually edited any data directly in the database + +#### It will be nearly impossible for us to help you without this info, so please try to be sure to include it with every help request so that we can try to get your problem sorted quickly. + +**__Please do not email for installation support. Github Issues allows us to share solutions so that other people can learn from them, which gives the community the most benefit.__** diff --git a/docs/installation/README.md b/docs/installation/README.md new file mode 100644 index 0000000000..b271569d25 --- /dev/null +++ b/docs/installation/README.md @@ -0,0 +1,13 @@ +--- +currentMenu: overview +--- + +# Installation Overview + +The installation instructions provided here are for a production installation of Snipe-IT. If you are a developer looking to contribute to Snipe-IT, please see the [Contributing](/contributing.html) page. + +Once you have [downloaded Snipe-IT](downloading.html), you'll need to complete all of the steps in the installation section, in addition to configuring your server. That means you will now create an empty MySQL/MariaDB database, [customize your configuration files](configuration.html), [install the dependencies with composer](composer.html), and run the [command line utility](command-line.html), and then configure your web server. + +Installation should take around twenty minutes or less, if nothing goes wrong, and if you're pretty familiar with web server configuration. + +If this all looks too overwhelming for you, we do offer [affordable hosted solutions](http://snipeitapp.com/hosting/) for folks who want to use Snipe-IT but don't know how to run a web server, or don't have time to keep up with updates. diff --git a/docs/installation/command-line.md b/docs/installation/command-line.md new file mode 100644 index 0000000000..39f3986386 --- /dev/null +++ b/docs/installation/command-line.md @@ -0,0 +1,53 @@ +--- +currentMenu: command-line +--- + +# Using the CLI Installer + +At this point you should have an *empty* database created, and all of your configuration settings set up the way you want them by carefully following the [configuration documentation](/installation/configuration.html) and editing the configuration files. + +Now, you need to create yourself an admin user. + +Use the following command to create your database tables, add a default user, create the default user groups and run all the necessary database migrations to ensure your database schema is up to date. + +----- + +#### Linux / OSX +``` +php artisan app:install --env=production +``` + +#### Windows + +Open `C:\inetpub\wwwroot\snipe-it` in Windows Explorer + +- Right Click and select `Use Composer here` +- Type `php artisan app:install --env=production` and follow the prompts + +----- + +When it asks you if you’re sure you want to run the migrations, type in `y`. You may have to do this a few times. + +----- + +### Seed the Database (Optional) + +During the `php artisan app:install` process, it will ask you if you wish to seed the database. + +Loading up the sample data will give you an idea of how this should look, how your info should be structured, etc. It only pre-loads a handful of items, so you won’t have to spend an hour deleting sample data, but this step is optional. If you don’t wish to seed the database, type in `n` when the installer asks you whether you want to seed. + +If you answer no, but change your mind after the installer is complete, you can run the database seeder by running: + +``` +php artisan db:seed --env=production +``` + +If you run this command on a database that already has your own production asset data in it, IT WILL OVER-WRITE YOUR ENTIRE DATABASE. ALL of your data will be gone forever. NEVER run the db seeder on production after on your initial install. + +----- + +### Update Your Secret Key (If you didn’t already) + +After running the `php artisan app:install --env=production` command above, the output of your terminal window should show you a generated secret key. If you missed it in all the scrollback, that’s okay, you can manually run `php artisan key:generate --env=production`. + +Update the value of `key` in your `app/config/production/app.php` file with the newly generated secret key. diff --git a/docs/installation/composer.md b/docs/installation/composer.md new file mode 100644 index 0000000000..480038dad2 --- /dev/null +++ b/docs/installation/composer.md @@ -0,0 +1,34 @@ +--- +currentMenu: composer +--- +# Install Dependencies with Composer + +Composer is a package manager for PHP that allows us to manage the dependencies for the various vendor packages we utilize in Snipe-IT. Vendor packages are PHP libraries that someone else wrote, and that we use in Snipe-IT to help make it awesome. + +These are not the same thing as the [system requirements](../requirements.html), which are technologies that the server itself needs in order to run Snipe-IT (such as a database, etc). + +__NOTE: Never run composer as a super-user or Administrator. Always run it as the user that owns the Snipe-IT files. Running composer as a super-user will break things in ways that will be difficult to debug later. Just don't do it.__ + +## Linux / OSX + +It is not required to install composer globally, however if you wish to, you can find instructions on how to do so on [the Composer website](https://getcomposer.org/). + +```bash +cd +curl -sS https://getcomposer.org/installer | php +php composer.phar install --no-dev --prefer-source +``` + +### For global composer installations + +```bash +cd +composer install --no-dev --prefer-source +``` + +## Windows + +- [Download Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe) from the Composer website. +- Move the `Composer-Setup.exe` file `C:\inetpub\wwwroot\snipe-it` +- Open `C:\inetpub\wwwroot\snipe-it` in Windows Explorer +- Right click and select `Composer Install`. This will install the dependencies. diff --git a/docs/installation/configuration.md b/docs/installation/configuration.md new file mode 100644 index 0000000000..94350b84b8 --- /dev/null +++ b/docs/installation/configuration.md @@ -0,0 +1,248 @@ +--- +currentMenu: configuration +--- + +# Snipe-IT Configuration Files + +
+ +## Set Your Environment + +Update the file `bootstrap/start.php` under the section Detect The Application Environment to include your server's hostname in the `production` array. This configuration option tells Snipe-IT whether it should run in development mode (local), staging, or production mode. __Unless you are a PHP developer setting up a local installation so that you can contribute code towards Snipe-IT, you should be running Snipe-IT in production mode__. + +To find out your local machine’s hostname, type `hostname` from a terminal prompt on the machine you’re installing it on. The command-line response is that machine’s hostname. __Please note that the hostname is usually NOT the same as the domain name__. + +So for example, if you’re installing this on your server named `CentOS-ip-9875`, the environmental variable section of `bootstrap/start.php` might look like this: + + +```php +$env = $app->detectEnvironment(array( + ... + 'production' => array('CentOS-ip-9875') +)); +``` +----- + +## Set Timezone and Language Preferences + +Open up `app/config/app.php` and edit the `timezone` and `language` settings to reflect your desired timezone and language. The default timezone is UTC. The timezone you use should be formatted as [an accepted PHP timezone](http://php.net/manual/en/timezones.php), so for example, for Pacific Time, you could use `America/Los_Angeles`: + +``` +'timezone' => 'America/Los_Angeles', +``` + +The default language is US English, however we have additional language translations available, thanks to a great community of people [helping us translate Snipe-IT](../translations.html). + +``` +'locale' => 'en', +``` + +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. + +| Language | Value | +| ------------- | ------------- | +|Arabic|`ar`| +|Chinese Simplified|`zh-CN`| +|Czech|`cs`| +|Danish|`nl`| +|Dutch|`nl`| +|English|`en`| +|English, UK |`en-GB`| +|Finnish|`fi`| +|French|`fr`| +|German|`de`| +|Hungarian|`hu`| +|Italian|`it`| +|Japanese|`ja`| +|Korean|`ko`| +|Malay|`ms`| +|Norwegian|`no`| +|Polish|`pl`| +|Portuguese|`pr-PT`| +|Portuguese, Brazilian|`pr-BR`| +|Romanian|`ro`| +|Russian|`ru`| +|Spanish|`es-ES`| +|Swedish|`sv-SE`| +|Thai|`th`| +|Turkish|`tr`| +|Vietnamese|`vi`| + +If you're interested in additional languages, or would like to help us translate some of the incomplete existing languages, please see the [Translations](../translations.html) page. + +----- + +## Edit Database Settings + +__Note: You must create the database yourself. Snipe-IT does not create the database or database users for you.__ + +Copy the example database config from `app/config/production/database.example.php` to `app/config/production/database.php`. Update the file `app/config/production/database.php` with your database name and credentials, replacing `snipeit_laravel` with your database name, `travis` with your database username, and so on: + +``` +'mysql'=> array( + 'driver' => 'mysql', + 'host' => 'localhost', + 'database' => 'snipeit_laravel', + 'username' => 'travis', + 'password' => '', + 'charset' => 'utf8', + 'collation'=> 'utf8_unicode_ci', + 'prefix' => '', +), +``` + +You can generally leave `charset`, `collation` and `prefix` as they are. + +You do not need to run migrations or worry about the database schema during the installation. The [command-line installer](/installation/command-line.html) will create the initial database tables for you. + +----- + +## Edit Mail Settings + +Copy the example mail config from `app/config/production/mail.example.php` to `app/config/production/mail.php`, and update the new `app/config/production/mail.php` file with your settings for SMTP server, email username and password. + +These settings will be used to send emails to your users, when they register and when they request a password reset. + +While your mail settings will vary depending on how you've set up your server, the one line you must change regardless of your configuration is: + +``` +'from' => array('address' => null, 'name' => null), +``` + +__Make sure as you edit this section that you change the **values**, not the **keys**.__ For example, + +``` +'from' => array('address' => 'me@example.com', 'name' => 'John Smith'), +``` + +is __correct__, while + +``` +'from' => array('me@example.com' => null, 'John Smith' => null), +``` + +is __incorrect__ and will cause errors when it tries to send email. + + +Make sure you enclose your values in single quotes. For example, + +``` +'username' => 'myusername', +``` + +is __correct__, while + +``` +'username' => myusername, +``` + +is __incorrect__ and will cause errors when it tries to send email. + +If you don't have an SMTP server to use, you can set the `driver` value to `mail`: + +``` +'driver' => 'mail', +``` + +### 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](https://www.godaddy.com/help/what-is-the-name-of-my-hosting-accounts-relay-server-953) 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): + + +| Setting | Value | +| ------------- | -----------| +|`driver`|`'smtp'` | +|`host`|`'smtp.gmail.com''` | +|`port`|`587` | +|`encryption`|`'tls'` | +|`username`|`'your_gmail_username'` | +|`password`|`'your_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](https://www.google.com/settings/security/lesssecureapps) and enable access for "less secure" apps: +- Then go [here](https://accounts.google.com/b/0/DisplayUnlockCaptcha) and click Continue. +- If you're still getting errors, try [this solution on StackOverflow](http://stackoverflow.com/a/26041277/200021). + +(More info on sending email through Laravel and Gmail is [available here](http://code.tutsplus.com/tutorials/sending-emails-with-laravel-4-gmail--net-36105), and more info on why Google makes you jump through these hoops is [available here](https://googleonlinesecurity.blogspot.co.uk/2014/04/new-security-measures-will-affect-older.html).) + +### 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](http://mandrillapp.com). Their free tier allows for 12k free sends a month, which should more than cover normal Snipe-IT email usage. + +----- + +## Application Settings + +Copy the example app config from `app/config/production/app.example.php` to `app/config/production/app.php`, and then update your new `app/config/production/app.php` with your URL settings. + + +``` +'url'=> 'http://www.yourserver.com', +``` + +**This value should begin with the protocol (http:// or https://), as reflected in the example above.** + +You should also change your secret key here from `Change_this_key_or_snipe_will_get_ya` to a random 32 character string. If you prefer to have your key randomly generated, run the `php artisan key:generate` command from the application root a little later in this process. + +----- + +## Set Directory Permissions + +You’ll need to make sure that the `app/storage` directory and its subdirectories are writable by your web server, since caches and log files get written there. You should use the minimum permissions available for writing, based on how you’ve got your web server configured. You also need to change permissions for your `uploads` directory for user avatars and model images. + +First, you'll need to figure out which user your webserver is running under. On Linux/OS X systems, it's usually something like "nobody", "apache", "httpd", "www", or "\_www" Determine that by using `ps auxwww` - then you can see who the server is running as. + +Once you've determined your webserver's user, you will want to make sure your webserver has ownership of the appropriate directories: + +```sh +chown -R that_username app/storage app/private_uploads 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 app/storage +chmod -R 755 app/private_uploads +chmod -R 755 public/uploads +``` +For help fixing permissions on IIS, see the [Windows Installation guide](server/windows.html). + +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 itself (Apache, IIS, etc) can write to files owned by the Snipe-IT user. + +__Note: It should go without saying, but 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 Cookies to HTTPS-only +As an extra security feature, Snipe-IT allows you to set your cookies to HTTPS-only, which will ensure that session cookies will only be sent back to the server if the browser has a HTTPS connection. + +If you are running Snipe-IT over SSL and wish to use this feature, copy the example session config from `app/config/production/session.example.php` to `app/config/production/session.php`, and then update your new `app/config/production/session.php` file to reflect: + +``` +'secure' => true, +``` + +If you have this option set to `true` in your session config, your users will not be able to login if they access Snipe-IT over the non-HTTPS connection. + +**Note: If you are NOT running Snipe-IT over SSL and you enable this option, your users will not be able to login. Only use this option if you are running Snipe-IT over SSL.** + +----- + +## 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] +``` + +**Note: If you are NOT running Snipe-IT over SSL and you enable this option, your users will not be able to access the site. Only use this option if you are running Snipe-IT over SSL.** diff --git a/docs/installation/downloading.md b/docs/installation/downloading.md new file mode 100644 index 0000000000..ebcb919408 --- /dev/null +++ b/docs/installation/downloading.md @@ -0,0 +1,29 @@ +--- +currentMenu: downloading +--- + +# Downloading + +The installation instructions provided here are for a production installation of Snipe-IT. If you are a developer looking to contribute to Snipe-IT, please see the Contributing page. + +#### Clone the Repository + +```bash +git clone https://github.com/snipe/snipe-it your-folder +``` + +or + +#### Download the source from [https://github.com/snipe/snipe-it/archive/master.zip](https://github.com/snipe/snipe-it/archive/master.zip) + +or + +#### Download and run the installer script (centos/redhat and debian/ubuntu) + +Note: requires Centos 6 or Ubuntu 14 or greater. + +```bash +wget https://raw.githubusercontent.com/snipe/snipe-it/master/install.sh +chmod 744 install.sh +./install.sh +``` diff --git a/docs/installation/manually-editing-data.md b/docs/installation/manually-editing-data.md new file mode 100644 index 0000000000..7a9ef6fb7a --- /dev/null +++ b/docs/installation/manually-editing-data.md @@ -0,0 +1,21 @@ +--- +currentMenu: manually-editing-data +--- + +# Manually Editing Data in the Database + +The short version: + +## Don't. + +If you start deleting records from tables manually, you will almost assuredly mangle your data in a way that will cause real problems. This software uses a relational database system, which means that some tables exist just to establish relationships between other pieces of data. When you delete part of that equation, Bad Things Happen™. + +We utilize soft deletes in Snipe-IT, which means records are never really deleted, they are simply marked as deleted. This is by design, so that you don't lose history on an asset when, for example, you delete a user. Just because the user is no longer at your organization, that doesn't mean you would want to wipe the previous history of the assets they had while they were there. + +## If you decide to do it anyway + +**ALWAYS back up your database before you start manually editing database records**, so that when it breaks everything (and it probably will), you will be able to restore it. + +If you absolutely insist on deleting data directly, make sure the corresponding records in the `asset_logs` table are also deleted. The `asset_logs` table holds all of the history for assets, accessories and users, and if you delete the assets, accessories, or users it ties together, things break. + +If all else fails, delete the contents of `asset_logs`. This should be considered an absolute last resort, as you will be wiping out the history of every checkin, checkout and file upload in the history of the app. diff --git a/docs/installation/proxy.md b/docs/installation/proxy.md new file mode 100644 index 0000000000..0bd312a89c --- /dev/null +++ b/docs/installation/proxy.md @@ -0,0 +1,69 @@ +--- +currentMenu: proxy +--- + +# Running Snipe-IT Through a Reverse Proxy + +
+ +If you wish to use a Reverse Proxy in front of your web server, you'll need to take a few extra steps to make it work. + +A typical Reverse Proxy scenario looks like this: + +Internet Reverse Proxy Server (Public & Private IPs) Web Server (Private IPs) + +The Reverse Proxy Server is functioning as a reverse proxy (Nginx, Squid, Apache's Mod_Proxy, or Varnish). + +In most deployments the Reverse Proxy will perform HTTP to HTTPS redirection and only pass requests and responses via HTTPS to the remote client. + +Scenario: **BROKEN** + +Client HTTPS Reverse Proxy Server HTTP Web Server + +Scenario: **WORKS** + +Client HTTP Reverse Proxy Server HTTP Web Server
+Client HTTPS Reverse Proxy Server HTTPS Web Server + + +## Explanation +In the above scenario the generated HTML will reference `http://` instead of `https://` for all assets. This causes most browsers to throw security warnings and refuse to display the content. (Typically, you'll see mixed content warnings because the browser won't load insecure elements on an SSL page.) + +__This assumes that your Reverse Proxy Server and Web Server are correctly configured and working properly. Meaning you have other correctly functioning Applications behind the proxy and the Web Server for Snipe-IT works properly if accessed directly.__ + +Snipe-IT is unaware that requests to the proxy are being handled through HTTPS instead of HTTP. As such no effort is made to generate HTTPS links for Assets (javascript, CSS, images, etc.) + +Snipe-IT needs to be made aware of the presence of the Reverse Proxy Server. The `X-Forwarded-Proto` header should be passed from the Reverse Proxy Server to the Web Server. + +## Server Configuration +In Nginx, you would use: + +``` +proxy_set_header X-Forwarded-Proto $scheme; +``` + +With Apache's Mod_Proxy, you would add: + +``` +RequestHeader set X-Forwarded-Proto "https" +``` + +to your virtual host configuration. + +## Snipe-IT Configurations + +Copy the `app/config/packages/fideloper/proxy/config.example.php` to `app/config/packages/fideloper/proxy/config.php`, and change + +``` +'proxies' => '*' +``` + +to + +``` +'proxies' => array('YOUR.IP.GOES.HERE'), +``` + +replacing `YOUR.IP.GOES.HERE` with the IP address(es) of your Reverse Proxy. Note that IPs and CIDR Notation are accepted. **Do not leave this as the default asterisk as that is highly insecure.** + +You may also want to see the [security notes](../security.html) for additional steps you can take for SSL configurations. diff --git a/docs/installation/server/README.md b/docs/installation/server/README.md new file mode 100644 index 0000000000..e4976b5b2c --- /dev/null +++ b/docs/installation/server/README.md @@ -0,0 +1,41 @@ +--- +currentMenu: server +--- + +# Server Configuration + +As mentioned, Snipe-IT is web-based software, which means it requires a web server to run. + +#### You must complete all of the steps in the installation section, in addition to configuring your server. That means you will [download the software](../downloading.html), [customize your configuration files](../configuration.html), [install the dependencies with composer](../composer.html), and run the [command line utility](../command-line.html), in addition to configuring your web server. + +Installation should take around twenty minutes or less, if nothing goes wrong, and if you're pretty familiar with web server configuration. + +__NOTE: You should never run Snipe-IT (or any website, ever) as a root (Linux) or Administrator (Windows). Create an unprivileged user and make them the owner of the files.__ + +
+
+ +
+
+ + Windows 2008 R2 With IIS Configuration Guide + +
+
+
+ +
+
+ +
+
+ + Linux / OSX Server Configuration Guide + +
+
+
+ +We also provide server configuration instructions for [XAMPP](xampp.html), [WAMP](wamp.html) and [Docker](docker.html). + +If this all looks too overwhelming for you, we do offer [affordable hosted solutions](http://snipeitapp.com/hosting/) for folks who want to use Snipe-IT but don't know how to run a web server, or don't have time to keep up with updates. diff --git a/docs/installation/server/docker.md b/docs/installation/server/docker.md new file mode 100644 index 0000000000..5a2c22dfaf --- /dev/null +++ b/docs/installation/server/docker.md @@ -0,0 +1,144 @@ +--- +currentMenu: docker +--- + +# Installing Snipe-IT on Docker + +The easiest way, by far, is to just use the version we push to [Docker Hub](https://hub.docker.com/r/snipe/snipe-it/): + +```sh +docker pull snipe/snipe-it +``` + +Then you have a functioning Snipe-IT container. Skip ahead to "How to get up and +running" to configure it and get it connected to your database. + +## How to get up and running + +The best way to handle all of the various settings for your various containers is to use an `env-file`. +See the Docker documentation for more details. It should be just a simple text file with environment +variable names and values, separated by ```=``` signs. + +Your `docker.env` should look something like this: + +```env +# Mysql Parameters +MYSQL_ROOT_PASSWORD=YOUR_SUPER_SECRET_PASSWORD +MYSQL_DATABASE=snipeit +MYSQL_USER=snipeit +MYSQL_PASSWORD=YOUR_snipeit_USER_PASSWORD + +# Email Parameters +# - the hostname/IP address of your mailserver +MAIL_PORT_587_TCP_ADDR=smtp.whatever.com +#the port for the mailserver (probably 587, could be another) +MAIL_PORT_587_TCP_PORT=587 +# the default from address, and from name for emails +MAIL_ENV_FROM_ADDR=youremail@yourdomain.com +MAIL_ENV_FROM_NAME=Your Full Email Name +# - pick 'tls' for SMTP-over-SSL, 'tcp' for unencrypted +MAIL_ENV_ENCRYPTION=tcp +# SMTP username and password +MAIL_ENV_USERNAME=your_email_username +MAIL_ENV_PASSWORD=your_email_password + +# Snipe-IT Settings +SNIPEIT_TIMEZONE=UTC +SNIPEIT_LOCALE=en +SERVER_URL=https://myserver.com +``` +First get a MySQL container running. MySQL 5.6 or earlier are easiest. + +```sh +docker run --name snipe-mysql --env-file=my_env_file -d -p $(docker-machine ip b2d)::3306 mysql:5.6 +``` + +**WARNING:** Newer MySQL containers (5.7 and later, or MariaDB) may run in strict-mode by default, and the initial migrations and application setup will fail in strict mode. If you want to use one of those versions, you need to disable strict mode first! + +That should set you up with your database to use. (You can also specify environment variables on the command-line instead of the env-file, but that can get very clunky very quickly; see ```docker run --help``` for details) + +* If your Email solution requires its own container, start that container or service. Make sure to expose port 587 for mail submission, and use ```--link mail:...```. + +### Start your Snipe-IT container + +First off, decide whether or not you want to have your Snipe-IT container manage SSL for you, or not. + +#### SSL disabled + +Start your Snipe-IT container - +```sh +docker run -d -p $(docker-machine ip b2d)::80 --name="snipeit" --link snipe-mysql:mysql --env-file=my_env_file snipe-it +``` + +#### SSL enabled +Start your Snipe-IT container - but make sure you can "mount" your local copies of your SSL key and SSL certificate onto the container. + +They're expected to be named exactly: `/etc/ssl/private/snipeit-ssl.key` and `/etc/ssl/private/snipeit-ssl.crt` for the key and certificate, respectively. + +```sh +docker run -d -P --name="snipeit" --link snipe-mysql:mysql -v /Absolute/Path/To/Your/SSL_Cert_directory:/etc/ssl/private --env-file=my_env_file snipe-it +``` + +### Email, Management, Access + +If you have a separate container running for email, you will also want a ```--link``` setting for email as well. + +You can find out what port Snipe-IT is running on with: + +```sh +docker port snipeit +``` + +And finally, you can initialize the application and database like this: + +```sh +docker exec -i -t snipeit php artisan app:install +``` + +(Go ahead and answer the questions however you like. Type 'yes' when asked whether or not you want to run migrations.) + +## For Development + +You can build the snipe-it image using the ```Dockerfile``` at the root directory of Snipe-IT by doing this: + +```sh +docker build -t snipe-it . +``` + +Then you can use your newly built image as ```snipe-it``` + + +When you call ```docker run``` - make sure to mount your own snipe-it directory *over* the /var/www/html directory. Something like: + +```sh +docker run -d -v /Path/To/My/snipe-it/checkout:/var/www/html -p $(docker-machine ip b2d)::80 --name="snipeit" --link mysql:mysql snipeit +``` + +Then your local changes to the code will be reflected. You will have to re-run ```composer install``` - + +```sh +docker exec -i -t snipeit composer install +``` + +You'll need to copy the docker/database.php file to ```app/config/production/``` , and copy the ```app/config/production/app.example.php to app/config/production/app.php``` + +And also app:install - + +```sh +docker exec -i -t snipeit php artisan app:install +``` + +And you may still need to generate the key with - + +```sh +docker exec -i -t snipeit php artisan key:generate --env=production +``` +While you're developing, you may need to occasionally run - + +```sh +docker exec snipeit composer dump-autoload +``` + +To fix the autoloading cache (if, for example, your class names change, or you add new ones...) + +**NOTE: When upgrading your docker install, make a note of the app key in `app/config/production/app.php`. If you are using LDAP, your LDAP server password is encrypted using this app key, and you will have a bad time if your app key changes. The upgraded docker WILL change your app key, so just replace the newly created on with your old one. ** diff --git a/docs/installation/server/linux-osx.md b/docs/installation/server/linux-osx.md new file mode 100644 index 0000000000..594bb089dd --- /dev/null +++ b/docs/installation/server/linux-osx.md @@ -0,0 +1,172 @@ +--- +currentMenu: linux-osx +--- + +# Installing Snipe-IT on Linux/OSX + +
+ + +## Using Apache + +The most common setup for Snipe-IT on a linux server is to use Apache, so if you're not sure what to pick, Apache might be the best bet, as it's free, easy to configure, and well documented. + +__The `DocumentRoot` for the app should be set to the `public` directory.__ + +In a standard Apache virtualhost setup, that might look something like this: + +``` + + + Allow From All + AllowOverride All + Options +Indexes + + + DocumentRoot /var/www/html/public + ServerName www.yourserver.com + # Other directives here + +``` + +**Note**: `/var/www/html/public` is a common path used on web servers, however you will want to change `/var/www/html/public` to wherever the `public` directory is in within the Snipe-IT files on your server. If you are using the installer script for Centos6+/Ubuntu 14+ remember to change your `Directory` and `DocumentRoot` to `/var/www/html/snipeit/public`. + +An OS X virtualhost setup could look more like: + +``` + + Allow From All + AllowOverride All + Options +Indexes + + + + ServerName "www.yourserver.com" + DocumentRoot "/Users/youruser/Sites/snipe-it/public" + +``` + +Snipe-IT requires `mod_rewrite` to be installed and enabled on systems running Apache. For more information on how to set up `mod_rewrite`, [click here](http://xmodulo.com/2013/01/how-to-enable-mod_rewrite-in-apache2-on-debian-ubuntu.html). + +__Note that in Apache 2.4, you may need to use `Require all granted` instead of `Allow From All`.__ + +----- + +## Using Nginx and PHP-FPM + +If you wish to use Nginx and PHP-FPM instead of Apache, PHP-FPM will need to be installed and setup to listen on a socket. For more information on how to setup PHP-FPM, [click here](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mysql-php-lemp-stack-on-ubuntu-12-04#step-five—configure-php). + +``` +server { + listen 80; + server_name localhost; + + root /Users/youruser/Sites/snipe-it/public/; + index index.php index.html index.htm; + + location / { + try_files $uri $uri/ /index.php$is_args$args; + } + + location ~ \.php$ { + try_files $uri $uri/ =404; + fastcgi_pass unix:/var/run/php5-fpm-www.sock; + fastcgi_index index.php; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + include fastcgi_params; + } +} +``` + +If you prefer to use a forced SSL setup, you can use the following configuration instead. + +``` +server { + listen 80; + server_name localhost; + + return 301 https://$server_name$request_uri; +} + +server { + listen 443 ssl; + server_name localhost; + + ssl_certificate /path/to/your.crt; + ssl_certificate_key /path/to/your.key; + ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2; + ssl_prefer_server_ciphers on; + ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-RC4-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:RC4-SHA:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!DSS:!PKS; + ssl_session_timeout 5m; + ssl_session_cache builtin:1000 shared:SSL:10m; + + root /Users/youruser/Sites/snipe-it/public/; + index index.php index.html index.htm; + + location / { + try_files $uri $uri/ /index.php$is_args$args; + } + + location ~ \.php$ { + try_files $uri $uri/ =404; + fastcgi_pass unix:/var/run/php5-fpm-www.sock; + fastcgi_index index.php; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + include fastcgi_params; + } +} +``` + +Note that with the SSL configuration you will need to adjust the path to your SSL certificate or it will not work. You can use a proper certificate generated from a CA or a self-signed certificate. For more information on creating a self-signed certificate, [click here](https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-nginx-for-ubuntu-12-04). + +----- + +## Running this on an EC2 Micro Instance + +Depending on your needs, you could probably run this system in an EC2 micro instance. It doesn't take up very much memory and typically won't be a super-high-traffic application. EC2 micros fall into the free/dirt-cheap tier, which might make this a nice option. One thing to note though - composer can be a little memory-intensive while you're running updates, and you may have trouble with it failing on a micro. You can crank the memory_limit up in php.ini, but EC2 micros have swap disabled by default, so even that may not cut it. If you run into totally unhelpful error messages while running composer updates (like simply 'Killed') or fatal memory issues mentioning phar, your best bet will be to enable swap: + + sudo /bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024 + sudo /sbin/mkswap /var/swap.1 + sudo /sbin/swapon /var/swap.1 + +If you need more than 1024MB then change that to something higher. + +To enable it by default after reboot, add this line to /etc/fstab: + + /var/swap.1 swap swap defaults 0 0 + + +----- + +## Notes on SELinux + +If you’re running SELinux, you’ll need to change the security context in order for the web server to be able to write to files where needed (log files, image uploads, sessions, etc). + +If you’re not sure, don’t worry about it unless you’ve set up Snipe-IT and you’re hitting permission errors even after you’ve updated the directory permissions to be writable. + +To tell if you’re running SELinux, you can run: + +``` +cat /etc/sysconfig/selinux +``` +or + +``` +sestatus +``` + +If it turns out you’re running SELinux, the syntax for changing the security context on a directory is: + +``` +chcon -type +chcon --reference +``` + +So for example, you might do something like: + +``` +chcon -R --type httpd_sys_rw_content_t /srv/snipeit +chcon -R --reference=/var/www/html /srv/snipeit +``` + +Depending on where your Snipe-IT files are located. diff --git a/docs/installation/server/wamp.md b/docs/installation/server/wamp.md new file mode 100644 index 0000000000..3fc5eeb40e --- /dev/null +++ b/docs/installation/server/wamp.md @@ -0,0 +1,9 @@ +--- +currentMenu: wamp +--- + +# Installing Snipe-IT on WAMP + +To install Snipe-IT on WAMP, see the video below on how to set up the server and database and then proceed to the documentation on [installing Snipe-IT for Linux/OSX](linux-osx.html). + +
diff --git a/docs/installation/server/windows.md b/docs/installation/server/windows.md new file mode 100644 index 0000000000..0d4580d3ab --- /dev/null +++ b/docs/installation/server/windows.md @@ -0,0 +1,83 @@ +--- +currentMenu: windows +--- + +# Install Snipe-IT on Windows 2008 R2 with IIS + +### Setting Up an IIS Website + +- Extract [Snipe-IT](../downloading.html) to `C:\inetpub\wwwroot\snipe-it` (folder name can be changed but we will reference it as is shown here) +- Run IIS Manager +- Right Click `Sites` and `Add Website` + +``` +Site name: Snipe IT +Physical path: C:\inetpub\wwwroot\snipe-it\public +Binding +Type: http +IP address: All Unassigned or a specific IP if you have one you will be using +Port: 80 or any you wish to use +Host name: assets.portal.local (this can be changed to suit your needs) +``` + +- Click `OK` + +Your site will now appear in the list. + +- Double click on your site +- Double Click `URL Rewrite` + - In the action pane click `Import Rules...` + - Click the `...` button + - Go to `C:\inetpub\wwwroot\snipe-it\public` + - Select `.htaccess` file + - Click `Open` then `Import` + - In the action pane click `Apply` + + +## Fix Permissions + +Add permissions for the IIS user for the `uploads` folder: + +- Go to `C:\inetpub\wwwroot\snipe-it\public` +- Right Click uploads -> Properties +- Go to Security Tab -> Edit +- Click Add and change location to local machine +- Type IUSR in object name box +- Click OK +- Give IUSR full control +- Click OK twice + +Add permissions for the IIS user for the `private_uploads` folder: + +- Go to `C:\inetpub\wwwroot\snipe-it\app` +- Right Click private_uploads -> Properties +- Goto Security Tab -> Edit +- Click Add and change location to local machine +- Type IUSR in object name box +- Click OK +- Give IUSR full control +- Click OK twice + +Add permissions for the IIS user for the `c:\windows\temp\` folder: + +- Goto `C:\windows\` +- Right Click temp -> Properties +- Goto Security Tab -> Edit +- Click Add and change location to local machine +- Type IUSR in object name box +- Click OK +- Give IUSR modify permissions +- Click OK twice + +Add permissions for the IIS user for the `storage` folder: + +- Go to `C:\inetpub\wwwroot\snipe-it\app` +- Right Click storage -> Properties +- Goto Security Tab -> Edit +- Click Add and change location to local machine +- Type IUSR in object name box +- Click OK +- Give IUSR full control +- Click OK twice + +Much to [@madd15](http://github.com/madd15) for writing up the Windows installation guide! diff --git a/docs/installation/server/xampp.md b/docs/installation/server/xampp.md new file mode 100644 index 0000000000..3450404078 --- /dev/null +++ b/docs/installation/server/xampp.md @@ -0,0 +1,9 @@ +--- +currentMenu: xampp +--- + +# Installing Snipe-IT on XAMPP + +To install Snipe-IT on XAMPP, see the video below on how to set up the server and database, and then proceed to the documentation on [installing Snipe-IT for Linux/OSX](linux-osx.html). + +
diff --git a/docs/installation/subdirectory.md b/docs/installation/subdirectory.md new file mode 100644 index 0000000000..2c489bbd95 --- /dev/null +++ b/docs/installation/subdirectory.md @@ -0,0 +1,56 @@ +--- +currentMenu: subdirectory +--- + +# Installing Snipe-IT Into a Subdirectory + +If you wish to run Snipe-IT in a subdirectory (`https://yourserver.com/snipe-it`) instead of at a primary domain (`http://yourserver.com`) or a sub-domain (`https://snipe-it.yourserver.com`), you'll need to go through the standard install steps 1-5, and then make a few small changes to your server configuration and `.htaccess` file. + +## Add an Alias Directive +In a standard Apache virtualhost setup, you'll need to add an `Alias` attribute to the virtualhost in your `httpd.conf`. That might look something like this, if your path to the Snipe-IT files were `/var/www/html/snipe-it/public`: + +``` + + + Alias /snipe-it "/var/www/html/snipe-it/public" + + + Allow From All + AllowOverride All + Options +Indexes + + + DocumentRoot /var/www/html/snipe-it/public + ServerName www.yourserver.com + # Other directives here + +``` + +(Make sure to restart the webserver after making configuration changes to the Apache configs.) + +## Modify Your .htaccess + +You'll need to add one line to your `.htaccess` file to make this work. Immediately beneath the `RewriteEngine On`, add the option `RewriteBase /snipe-it`, once again assuming that your subdirectory URL is `http://yourserver.com/snipe-it`. + + ``` + + + Options -MultiViews + + + RewriteEngine On + RewriteBase /snipe-it + + # Uncomment these two lines to force SSL redirect + # RewriteCond %{HTTPS} off + # RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L] + + # Redirect Trailing Slashes... + RewriteRule ^(.*)/$ /$1 [L,R=301] + + # Handle Front Controller... + RewriteCond %{REQUEST_FILENAME} !-d + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^ index.php [L] + +``` diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000000..f32be4344d --- /dev/null +++ b/docs/license.md @@ -0,0 +1,13 @@ +--- +currentMenu: license +--- + +# License + +Copyright (C) 2013-2014 Alison Gianotto - snipe@snipe.net + +This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License along with this program. If not, see . diff --git a/docs/manual/README.md b/docs/manual/README.md new file mode 100644 index 0000000000..4a5bac15f8 --- /dev/null +++ b/docs/manual/README.md @@ -0,0 +1,55 @@ +--- +currentMenu: manual-home +--- + +# Snipe-IT User's Manual + +(This manual is a work in progress - please check back often.) + +## Basic concepts + +### Checkin/Checkout + +Checking in and checking out are two primary concepts behind Snipe-IT. When you checkout an asset, license or accessory, you’re marking them as being in the possession of someone else. This means that they cannot subsequently be checked out to another person until they are checked back in. This prevents “double-booking” assets, where one asset has been promised to or assigned to multiple people. + +When an employee leaves your company, or if an asset, license or accessory is not functioning properly, you would check it back in. Checking it back in indicates that it’s back in your possession, or potentially out for repair. It’s up to you to decide what status to assign it, based on the condition of the asset. + +----- + +### Status Labels + +Status labels are used to describe the state of the asset. You can add as many status labels as you’d like. Each status label will have one of four characteristics that describe the state of assets with that status label: + +Undeployable: these assets cannot be assigned to anyone. + +Deployable: these assets can be assigned to people + +Archived: these assets cannot be assigned to people, and will only show up in the Archived view + +Pending – these assets can not yet be assigned to anyone. + +Use status labels however you see fit. You can just keep the starter labels we set up for you, or you can flesh out a detailed set of statuses that will make sure your team always knows exactly what’s going on with each asset. + +If you set up your status labels well, they can be enormously useful. A status label that is a pending label named “Awaiting Re-Imaging” tells your team that this item can’t be deployed because it’s still in the re-imaging stage and isn’t ready yet. Once it’s ready, your team can update the status to “Ready to Deploy”, and then it’s added to the pool of available deployable resources. + +----- + +## Getting Started + +### Setting up Locations + +If you have a fresh install of Snipe-IT, it can be confusing on where to get started. The best place to start is to set up your locations. Even if you only have one location, you’ll want to get that set up first, since users, assets and many other things within the Snipe-IT system rely on it. + +From here you can start adding users if you want, or move on to adding asset models and assets. + +### Asset Categories + +Asset categories are used by both assets and accessories. Categories describe the general type of asset or accessory, such as “wireless keyboards”, “laptops”, and so on. Categories are important because they contain attributes that are inherited by both the assets and accessories that long to them, such as whether to require the user to click on a link to show that they have received the asset or accessory, and whether or not the user should be emailed a EULA. + +Every asset and accessory needs to belong to a category, so you’ll need to set these up before adding assets. + +### Asset Models + +Every asset needs an asset model, so setting these up next will help you start adding assets. Asset models can be things like the make and model of a laptop or desktop machine (Apple 13″ Retina, for example). When you create new assets, you’ll select whichever asset model makes sense. + +Asset models are important because they carry certain attributes which are inherited by the assets you, such as depreciation type, end of life, and whether or not to show MAC address fields on the asset. diff --git a/docs/manual/alerts.md b/docs/manual/alerts.md new file mode 100644 index 0000000000..5851b10b4a --- /dev/null +++ b/docs/manual/alerts.md @@ -0,0 +1,17 @@ +--- +currentMenu: alerts +--- + +# Configuring Email Alerts in Snipe-IT + +To set up the cron to run every day, set up your crontab as: + +``` +@daily /path/to/php /path/to/your/snipe-it/artisan alerts:expiring +``` + +To set it to run every week, use: + +``` +@weekly /path/to/php /path/to/your/snipe-it/artisan alerts:expiring +``` diff --git a/docs/manual/backups.md b/docs/manual/backups.md new file mode 100644 index 0000000000..1969d7cd09 --- /dev/null +++ b/docs/manual/backups.md @@ -0,0 +1,26 @@ +--- +currentMenu: backups +--- + +# Automated Backups + +In `v2.0` and later, Snipe-IT can automatically create a zipped backup of your database dump and any files you've uploaded. You can run this command manually by entering: + +``` +php artisan snipeit:backup +``` + + +To set up the cron to run every day, set up your crontab as: + +``` +@daily /path/to/php /path/to/your/snipe-it/artisan snipeit:backup +``` + +To set it to run every week, use: + +``` +@weekly /path/to/php /path/to/your/snipe-it/artisan snipeit:backup +``` + +You will need to make sure that mysqldump is installed and set in your path. If mysqldump isn't in your path, you can set it manually by copying `/app/config/packages/schickling/backup/config.example.php` to `/app/config/packages/schickling/backup/config.php` and updating the mysqldump path information. diff --git a/docs/manual/custom-fields.md b/docs/manual/custom-fields.md new file mode 100644 index 0000000000..e84929e989 --- /dev/null +++ b/docs/manual/custom-fields.md @@ -0,0 +1,54 @@ +--- +currentMenu: custom-fields +--- + +# Custom Fields and Fieldsets + +Custom fields and fieldsets are available in Snipe-IT versions `2.1.0-pre` and later. + +Custom fields allow you to track additional information about your assets that the default asset attributes don't cover. + +Think of custom fieldsets as collections of custom fields. You can have a custom fieldset with just one custom field in it, or multiple custom fields. The idea of fieldsets is to keep commonly used fields grouped together so you don't have to add fields one-by-one to asset models. + +Custom fieldsets are assigned at the asset model level. So, for example, if you track mobile phones as Assets, you could create custom fields for "IMEI", "SIM", "Phone Number", etc. + +![Create mobile phones fieldset](/img/sim.png) + +You would then add all of those mobile phone related fields to a new "Mobile Phones" custom fieldset, and assign it to one of your mobile phone asset models. + +![Create mobile phones fieldset](/img/mobile-phones.png) + +When you're adding a field to a fieldset, you can select whether that field should be required, what order it should appear in, and then select the fieldset to add from the select box. + +![Create mobile phones fieldset](/img/add-to-fieldset.png) + +Then, for any mobile phone assets you create that belong to that asset model, the custom fields attributes will automatically appear. + +To break it down step by step: + +- Create the new custom fields you want in your custom fieldset. +- Create the new custom fieldset, and add the custom fields you just created. +- Go to Admin > Asset Models and edit an asset model, selecting the custom fieldset you just created. + +You can create the fields first, or the fieldset first, but be sure to add the new fields to your fieldset, and then associate that fieldset to an asset model to see those new fields on your asset forms. + +Once your asset models have custom fieldsets associated with them, your new values will appear on the asset view and edit pages, and in the main asset listing table. You will be able to search/sort on these fields (as well as show/hide them in the table view) the same as you can the other built-in fields. + +### Custom Field Validation + +We have provided support for basic input validation on the custom fields you create. When creating the fields, you'll have the option of selecting the `Format` the text input for your new fields should be in when your admins add or edit assets. You have several pre-defined options: + +| Format | Description | +| ------------- | ------------- | +|`ANY`|No input validation. Any text is acceptable.| +|`ALPHA`|Any alpha numeric text.| +|`NUMERIC`|Any numeric text.| +|`MAC`|Text formatted in MAC address format.| +|`IP`|Text formatted as an IPv4 address. (IPv6 is coming soon.)| +|`CUSTOM`|Custom regular expression.| + +If you select `CUSTOM`, be sure to enter a valid regular expression in the `Custom Format` box below that select box. + +### Notes: + +There is currently no ability to import custom fields while importing assets. That's coming soon. diff --git a/docs/manual/importing-assets.md b/docs/manual/importing-assets.md new file mode 100644 index 0000000000..9ffaea13fe --- /dev/null +++ b/docs/manual/importing-assets.md @@ -0,0 +1,74 @@ +--- +currentMenu: importing-assets +--- + +# Importing Users and Assets + +
+ +There is an asset import tool in later versions of Snipe-IT ( > `1.2.8`). It is available through the command-line only, as very large file uploading and processing will cause memory exhaustion issues on many servers*. + +*This web-based importer should be limited to imports of 1000 records at a time or less. We're working on making it able to handle more records at a time. + +Make sure you have your organization's domain name filled out in the `domain` value in `app/config/production/app.php`, so that it knows what domain to use when generating email addresses if none are provided in your CSV. + +## Usage: + +``` +php artisan asset-import:csv path/to/your/file.csv --email_format=firstname.lastname --username_format=firstname.lastname +``` + + +| Option | Values | Required | +| ------------- | ------------- | +|`email_format`|`firstname`, `firstname.lastname`, or `filastname` (for first initial, last name)| Yes | +|`username_format`|`firstname`, `firstname.lastname`, `filastname` (for first initial, last name) or `email`| Yes | + + +## CSV Format +The importer will be looking for a CSV in the format of: + +``` +Name (Firstname Lastname), Email, Username, Asset Name, Asset Category, Asset Model, Manufacturer, Asset Model Number, Asset Serial, Asset Tag, Location Name, Asset Notes, Purchase Date, Purchase Cost +``` + +The importer will ignore the first line of your CSV, so if you don't have a header row, you should add one. **There should not be any blank lines at the end of the CSV.** + +[__Download a sample CSV with dummy data__](http://docs.snipeitapp.com/sample-assets.csv) + +| Field | Example Data | Required | Notes | +| ------------- | ------------- | +|Name|`Firstname Lastname` | No| No commas. First name first, last name last | +|Email| `you@example.com`| No|If empty, will be generated using the `email_format` and `domain` you provide in your `app/config/production/app.php`| +|Username| `yourname.lastname`| No|If empty, will be generated using the `username_format` you provide in the import command| +|Asset Name |`Karen 2015`| No | | +|Asset Category |`Laptop`| Yes | Created if it doesn't exist | +|Asset Model |`MBP Retina 13-inch`| Yes |Created if it doesn't exist | +|Manufacturer Name| `Apple`|Yes | Created if it doesn't exist | +|Asset Model No.| `MacbookPro12,1`| No | | +|Asset Serial | `C20095805496869045H6`| No | | +|Asset Tag | `KJH90890`| Yes | | +|Location Name | `San Diego`| Yes | Created if it doesn't exist | +|Asset Notes | `Karens old machine`| No | | +|Purchase Date | `2015-01-12 07:30:30`| No | Can take any date format that can be translated by `strtotime()`| +|Purchase Cost | `2999.99`| No | Cost of asset| + +## What It Does + +When you execute this command with a valid path to your CSV, the importer will: + +- Split the user's name, creating `firstname` and `lastname`. +- If not user is provided, it assumes the asset is Ready to Deploy. +- If a user's name is provided, it assumes that asset is assigned to them +- If a user's name is provided but no email is provided, it will generate an email address using your domain and the pattern you specified in `email_format` +- Generate a password for the new user if a user's name is provided +- Create the user if they don't exist (based on their email address) +- Determine if the asset model exists based on Asset Model Name and Model Number combination +- Create the asset models, locations, category, etc if they don't currently exist, skip them if they do. +- If no user is provided, the asset gets created as ready to deploy instead of checked out to a user + +When using this, __BACK UP YOUR DATABASE FIRST__. This is experimental, and it might cause unexpected results with your data. There's some data cleansing and checking that needs to be built in before it's bulletproof. + +## Limitations & Notes + +The importer isn't very smart. It currently does not do any validation other than checking to see if the record already exists in the database. It doesn't know that `Dell Inspiron` is the same asset as `Dell Insprion`. The quality of your data will make a big difference in the results you get, so if there's a lot of inconsistency, you're going to end up with with duplicates because the app has no way of knowing what you **meant** from what you wrote. diff --git a/docs/manual/importing-licenses.md b/docs/manual/importing-licenses.md new file mode 100644 index 0000000000..326c87510a --- /dev/null +++ b/docs/manual/importing-licenses.md @@ -0,0 +1,69 @@ +--- +currentMenu: importing-licenses +--- + +# Importing Users and Licenses + +
+ +There is a license import tool in later versions of Snipe-IT ( > `1.2.10`). It is available through the command-line only, as very large file uploading and processing will cause memory exhaustion issues on many servers. We'll be working on a way to make this web-based and chunk data in the future. + +## Usage: + +``` +php artisan license-import:csv path/to/your/file.csv --domain=yourdomain.com --email_format=firstname.lastname +``` + + +| Option | Values | Required | +| ------------- | ------------- | +|`domain`| a domain name string formatted as yourdomain.com| Yes| +|`email_format`|`firstname`, `firstname.lastname`, or `filastname` (for first initial, last name)| Yes | + + +## CSV Format +The importer will be looking for a CSV in the format of: + +``` +User Name, User Email, Username, Software Name, Serial, Licensed to Name, Licensed to Email, Seats, Reassignable, Supplier, Maintained, Notes, Purchase Date +``` + +The importer will ignore the first line of your CSV, so if you don't have a header row, you should add one. + +[__Download a sample CSV with dummy data__](http://docs.snipeitapp.com/sample-licenses.csv) + +| Field | Example Data | Required | Notes | +| ------------- | ------------- | +|User Name|`Firstname Lastname` | No| No commas. First name first, last name last | +|User Email| `you@example.com`| No|If empty, will be generated using the `email_format` and `domain` you provide in the import command| +|Username| `agianotto`| No|This will be required in 2.0| +|Software Name| `Adobe Photoshop 5`|Yes|Name of the software| +|Serial|`8495867487HJGJ`|Yes|Serial number for the software| +|Licensed To Name|`Grokability, Inc`|No|Name the license was registered to, if applicable| +|Licensed To Email|`snipe@grokability.com`|No|Email the license was registered to, if applicable| +|Seats|`5`|Yes|Number of seats the license has, in numeric format| +|Reassignable|`Yes`|No|Whether the license can be reassigned| +|Supplier|`Acme, Inc`|No|Software supplier's name| +|Maintained|`Yes`|No|Whether the license is maintained by the supplier| +|Asset Notes | `Expensed to client XYZ`| No | | +|Purchase Date | `2015-01-12 07:30:30`| No | Can take any date format that can be translated by `strtotime()`| + +## What It Does + +When you execute this command with a valid path to your CSV, the importer will: + +- Split the user's name, creating `firstname` and `lastname`. +- If not user is provided, it assumes the asset is Ready to Deploy. +- If a user's name is provided, it assumes that asset is assigned to them +- If a user's name is provided but no email is provided, it will generate an email address using your domain and the pattern you specified in `email_format` +- Generate a password for the new user if a user's name is provided +- Create the user if they don't exist (based on their email address) +- Determine if the supplier exists, create it if it doesn't +- Create the appropriate number of license seat records + + +When using this, __BACK UP YOUR DATABASE FIRST__. This is experimental, and it might cause unexpected results with your data. There's some data cleansing and checking that needs to be built in before it's bulletproof. + +## Limitations & Notes + +The importer isn't very smart. It currently does not do any validation other than checking to see if the record already exists in the database. It doesn't know that `Aobe Acrobat` is the same asset as `Adobe Acrobat`. The quality of your data will make a big difference in the results you get, so if there's a lot of inconsistency, you're going to end up with with duplicates because the app has no way of knowing what you **meant** from what you wrote. diff --git a/docs/manual/labels.md b/docs/manual/labels.md new file mode 100644 index 0000000000..d91295ee0b --- /dev/null +++ b/docs/manual/labels.md @@ -0,0 +1,15 @@ +--- +currentMenu: labels +--- + +# Generating Asset Labels + +Generating labels for your assets is very simple in Snipe-IT. Simply go to any of the asset listing views (Ready to Deploy, Deployed, etc) and use the checkboxes in the leftmost column to select the assets you'd like to generate labels for. Once you've finished your selection, scroll down to the bottom of the asset listing table, and select "Generate Labels" from the dropdown list. + +![Generate labels](/img/labels.png) + +This will generate labels that should fit Avery 5027, 5026* and 8425 in portrait mode, or a similarly-sized two-across, eighteen-label (in portrait mode) sheet. There is enough padding around the labels to provide some flexibility with your choice of label sheets. + +**NOTE: You must have barcodes enabled in Admin > Settings for labels to be generated.** + +* Avery 5026 has a color band on the left that may make the QR code difficult to read diff --git a/docs/manual/sample.csv b/docs/manual/sample.csv new file mode 100644 index 0000000000..878d42cecf --- /dev/null +++ b/docs/manual/sample.csv @@ -0,0 +1 @@ +Name,Email,Category,Item,Brand,Model Number ,Serial,Tag,Location,Notes Daryl Maxwell,enim.diam.vel@Maurisnulla.edu,vulputate,et nunc.,"tempus, lorem",60F252A1-2C53-D4F0-AD05-E93D5B00C3C6,F340DE6D-B958-4EB6-C5E7-9FFD588BDAAF,54DB759D-3947-2A24-99C4-CC3CBC84BD7F,Halifax,ante. Maecenas Uriel Wall,ornare.elit.elit@sitametdiam.com,rutrum,"et, magna.",urna.,1D95F908-95CD-3521-553B-42F4A8004C5D,1E924DCF-B1A3-A0A0-5B98-FDD97737A1EB,50DEE567-752F-AF3A-8276-A4DAED159A1F,Akehir,Aenean eget metus. In nec Hadley Hardin,Ut.nec.urna@pedeNunc.ca,"nec tempus scelerisque, lorem",eget mollis,auctor,66D89368-C76B-7566-9C9A-66F80BC138D1,37961735-B900-0276-AE3C-F858A2215B2B,FDBFC6EC-D0D5-35F3-3D7B-EF1F2C6F77B8,Pictou,justo eu arcu. Morbi sit amet massa. Althea English,,vel sapien,Proin eget,"convallis, ante",9576799F-C50D-6DDF-FC5B-D41069FE17D4,AF297E73-389C-E91D-960D-BAEE39A28C03,29D0A010-92E2-6A42-59B6-6111558F5EA3,Provost,a odio semper cursus. Integer mollis. Integer tincidunt aliquam arcu. Haley Medina,Integer.sem@vulputatemaurissagittis.org,nisl,gravida nunc,nascetur ridiculus,D30475CB-B41B-71A9-AF88-B39AF6EADD14,E6BC3C50-8AB3-231C-D8FF-2D22F7461232,F9B257EF-B3DC-409E-ACB7-3C94C5DF8E48,Pozna,"at, libero. Morbi accumsan laoreet ipsum. Curabitur" Cody Dorsey,imperdiet@Morbinequetellus.com,Donec,metus. Vivamus,sagittis,21FB961B-8F2A-4E60-AECF-E0E74C5C9B18,89FD6952-5D3B-ED5D-9DD5-9DFC52875F27,E935209A-7935-3724-C5D6-47DE5B10A4E1,Prince Albert,"fermentum risus, at fringilla purus mauris a nunc. In" Price Walter,justo.nec.ante@etmalesuada.org,"ut,",et malesuada,vehicula,260C5E2F-F542-7E56-EDC0-D2361C7203AD,5FE79D24-04BB-561C-5694-E01864AD9116,F5755B01-E067-B8B2-8FB3-48C1007EB520,Cropalati,vitae odio sagittis Althea Bentley,et.commodo.at@famesacturpis.co.uk,"vestibulum lorem,",netus et,ornare lectus,BA33A0AB-171E-49C4-6977-7B589A07A912,43DE6FE4-BC99-8132-CE52-79F338782199,C497565C-3E82-BD52-A4D4-F6D2B602C607,Agartala,augue malesuada malesuada. Integer Jordan Finch,,sociis natoque penatibus,"tempus non,",arcu imperdiet,6C369B1E-7204-5ADF-7027-5A37A0DA4AD6,3A82675C-EC7C-77FC-C6DF-38BC58374772,C0118A89-9FD0-E1B7-D21D-E1E286829083,Lens,et nunc. Quisque ornare tortor at risus. Nunc ac Zorita Cooley,amet.lorem@adipiscingenim.org,"Donec tempus, lorem",tincidunt dui,Pellentesque ultricies,4D67FB02-1DA7-A489-ECF3-FB1F5D10BD2E,0A37428F-46C8-FE14-5089-CEA1F26C91ED,5C91288D-8B1C-F660-45D7-433C9918956A,Grand-Leez,tempor bibendum. Donec Alea Walsh,nisi.nibh@commodoauctor.ca,dolor. Fusce mi,orci. Ut,"lorem, auctor",336D3F97-A966-BD28-A394-36192206E6A9,6DE7E627-A320-D751-9CF7-1958974E8A1E,20E95D8F-4EBD-9415-CEEE-70598DA6B55B,Santa Vittoria in Matenano,"tempus scelerisque, lorem ipsum sodales" Jin Moses,,Suspendisse,sit amet,magna. Suspendisse,D778A12A-0CC7-B0E4-0E01-8A2098A4DA4D,89446D66-DF81-7FFF-702A-8E002A58D588,D8B77CFC-EBCD-D8A5-CB80-75C82ECE7091,Wiekevorst,"nec, diam. Duis mi enim, condimentum eget," Lavinia Garrison,egestas.lacinia.Sed@eget.ca,penatibus et,nibh. Phasellus,eu,D7BEE05E-CBFA-69E2-5837-122E7BB38D30,D0202A27-28AC-6B5D-A7FF-76EC9674D2F4,0B869456-C3C6-D498-A83A-5844EF82F643,Frascati,Duis volutpat nunc sit amet metus. Aliquam erat Rama Montgomery,fermentum.vel@purussapien.co.uk,"elit. Aliquam auctor, velit",blandit mattis.,enim. Mauris,B6D4A87F-3885-DFBC-FF6C-688C66729A99,D4E141C8-9D6D-86B6-3000-B0EA184C217C,9E51B44E-EC5E-4613-2570-3E72FBCB1247,Guysborough,"tempus eu, ligula. Aenean euismod mauris eu elit. Nulla" Brock Pickett,at.auctor@auctorMauris.net,Donec fringilla. Donec feugiat,magnis dis,malesuada fames,52384EE0-069C-9356-88E0-D94028C2EB39,A3DAA4E8-1783-C285-10AB-21B1659FC1E2,AE68BA94-23F8-B07E-43B7-4D215860E03D,Tenby,"cursus luctus, ipsum" Bevis Frost,,feugiat metus sit,"ullamcorper, nisl",In,85F8BFC5-D224-2F96-7CDF-8FB67D68C09B,45AD10B3-F271-DD1C-C192-02FD5721C167,D0751EA7-B364-6F75-CA1B-5AA4C280535A,Burnie,sagittis. Duis gravida. Praesent eu nulla at sem Wesley Walton,risus@arcuAliquam.edu,"suscipit, est",ullamcorper magna.,quis,28C4AFEB-39BA-766B-C508-863DFACB147F,5DF6047E-2C6A-ECEF-BE00-3D607565185D,68AC6108-D720-C887-4636-9F1C69B9A007,Gembloux,"in, cursus et, eros. Proin" Cullen Shepherd,fermentum.metus.Aenean@nonummyultriciesornare.co.uk,Pellentesque ultricies dignissim lacus.,pede nec,adipiscing lacus.,202F8CE2-38AC-A131-16E3-B698BC1B966C,80200A77-22F1-A324-4110-9E8AB771E9B5,0E0B37EF-18A1-0D7B-C540-CBC457AC8B01,Market Drayton,fermentum convallis ligula. Donec luctus aliquet odio. Etiam Adam Matthews,,mauris.,felis. Nulla,"at,",D06EE2EB-AA91-D8EC-6B4F-E6B8648F5230,61BEF919-420D-CD65-01B5-ACBC7A58A166,82485625-880F-94EF-BEE2-D237698F95C9,Biaystok,laoreet lectus quis massa. Arthur Porter,nibh.Aliquam@duiCumsociis.net,Duis,luctus et,"enim, gravida",A880E563-122F-50BE-2A6B-3429C786C345,871787FD-7B4D-6C75-DE1C-D11FF1DADF50,D63B956B-DB6F-548F-8E89-B6520E45AFC0,Murcia,"facilisis non, bibendum" Fletcher Pittman,,sodales nisi magna,Donec egestas.,posuere,DB24FCA0-392B-F2A5-6377-F54C3AB176B5,7E7494C9-F204-1A05-E095-1AD2C17EE837,058D7BC3-2CC2-7CAA-982B-60246EA86432,Argyle,"accumsan convallis, ante lectus convallis est, vitae sodales nisi magna" Jael Mack,risus.Nulla@metus.org,"dolor elit, pellentesque a,",non leo.,Maecenas malesuada,0E50AA10-3D27-FF70-6FB4-D3DA21784194,C58AA7B9-7291-E937-97F1-6D46FC945BCC,D0211F92-2BD7-B2ED-D268-A5611D692278,Bydgoszcz,"magnis dis parturient montes," Lucius Gaines,cursus.diam@duiCras.ca,justo sit amet,nec tempus,risus.,AD82E7B7-F144-C237-FC1C-01676FECFD0A,433BF0D7-D023-F4AB-A82B-397F92F5560F,AAA13BE2-C62C-E7B9-A3C8-9CA8092ACF2F,Susegana,ultricies sem magna nec quam. Curabitur vel lectus. Zeph Chambers,,"sed,",Nunc pulvinar,ac,ED430E4C-96F3-268F-9D60-12014A55A363,32EEF38F-A7FE-44B9-17AB-79111C5C5132,39B7AAC9-4087-8879-B445-EFA6D09E5168,Valcourt,non justo. Proin non massa non Martha Conrad,Morbi.neque.tellus@dui.net,lectus,"suscipit, est",placerat,D50D4A93-2335-3213-0B6D-2D0CD198836E,6E88F862-CEF2-C2B4-B97B-F6AC006B8CC3,0C4F6292-ADE9-7074-A67A-F1D638D7D35A,Chiavari,Nulla Ima English,,"amet, faucibus ut,",orci. Ut,non massa,AF38AC9F-01B0-9F56-17D7-92E011B59350,6B6980AC-AEB1-4C1B-4B14-C04FEE6C5078,C35B4D11-34D7-5B2A-0A99-CD323CEAEB74,Virginia Beach,"lacus vestibulum lorem," Leandra Boyle,Donec.feugiat@Nullam.org,nibh.,velit egestas,"mauris elit,",766CB9E0-CEAB-E499-78CD-E74F4C2A56AA,3ED17E48-2B44-E467-4753-F0A6B8126858,5C87E5B8-C92A-DE4B-D784-AA00690B688F,Cleveland,"Nam ligula elit, pretium et," Irene Scott,,vel,mauris id,elit.,17EB8A0F-49EA-7D0C-FF61-53FC509D3067,CB53C6CB-7DB7-3B1A-A24E-874D185BB4C3,0C80BCF9-DF3B-BC35-B02B-273CBE110E52,Navadwip,dignissim. Maecenas ornare egestas ligula. Nullam feugiat placerat velit. Quisque Blaze Moreno,adipiscing.lacus.Ut@duiaugue.ca,"porttitor vulputate, posuere",ut lacus.,"blandit at,",89BA4ECF-1697-3AB1-7A76-38B4E7707FE0,AEC67494-8F3C-7B3C-A742-95C90002DF5D,6D84FE16-8395-4F77-213A-6B54D2CA6F7E,Giardinello,sollicitudin orci Marsden Castro,,erat,mus. Aenean,"sem elit,",747ED9E8-49CB-471A-E1ED-D8CB6FCF44C6,71E99620-A233-480D-1CF6-2B928FDF23F3,EBE8CA6B-4D47-6D43-4A81-01A7C7DE4EEA,Lombardsijde,nisl. Maecenas malesuada fringilla Ivor William,velit@utdolordapibus.co.uk,consectetuer adipiscing,Sed et,lacus. Quisque,25BB8776-0A6C-6977-C1D9-4688C2C86A9A,6C9E7AF1-CB79-C009-FD0D-FC6B04507687,18EB075A-3C7E-6430-12B6-9D6F3F7759E1,Westrem,"ullamcorper eu, euismod ac," Brandon Bray,ante@gravidamaurisut.edu,vitae mauris,velit in,"vulputate,",1EE64085-0472-E91A-3039-4D4BAECC15CF,43009A54-E097-2969-CA1F-53E150D7572C,AD7A36F2-A055-D7C7-FAFF-03C7BF39C88C,Gropetersdorf,vitae diam. Proin dolor. Nulla semper tellus id nunc Jillian Marquez,,"Quisque imperdiet, erat nonummy",enim. Etiam,Mauris,07275F42-BDF1-B7BF-1874-E3B21C4D17FC,F7AB1F1C-E3BF-166F-1359-C3A18984813D,3A96E315-AE77-52BA-7C66-F009431E6D12,Saint Louis,"vestibulum lorem, sit amet ultricies sem magna nec quam. Curabitur" Maryam Alvarado,id@natoquepenatibus.net,"porttitor vulputate,",Vivamus rhoncus.,amet,FDEF0A16-8DDC-EAA8-14B2-429A469E52EA,FEE7C920-6DA3-B8D8-3C10-F29FB4BFDFCD,A7683AAD-90B5-F470-3AAA-672255FE80F9,Verrayes,ligula. Aenean euismod mauris eu elit. Nulla facilisi. Sed neque. Xaviera Calhoun,Nam@Duis.net,laoreet lectus quis massa.,nec tellus.,dui.,D26D5C0C-9454-8E3F-54CB-B9F887BE1427,C146A0ED-82B8-92BD-D61A-4F75269A3BC6,E71CC2A3-1FEF-8286-4BFA-D43D89938DEE,Krak_w,"mi. Duis risus odio, auctor vitae, aliquet nec, imperdiet nec," Rashad Finley,mauris.elit.dictum@velturpis.org,"Fusce dolor quam,",metus. Vivamus,tempus risus.,041FC172-D5E9-159B-9701-A530077CDB31,00AB6A98-A66C-6617-F7E6-806467B8B14C,16351136-6919-76C3-259A-4A07E9F51111,Froidchapelle,"id, erat. Etiam vestibulum massa rutrum" Ulric Nichols,dui@ultricesDuis.edu,"vel, vulputate",risus. Morbi,primis in,9072BF87-4197-8E8D-32E3-7A10EA2B1F29,A159F02C-3D4B-4CB7-A5CC-294C29E41626,2CC0F583-8470-CA35-84C6-36F7D8551FDA,Rigolet,"parturient montes, nascetur ridiculus mus. Aenean eget magna." Tate Cruz,adipiscing.ligula@ametluctus.org,odio.,tortor. Nunc,Donec fringilla.,B50A0494-C49A-D4B7-A275-BA993CD37006,11D0D0B8-A50F-C75C-12B9-356577413248,51FB7F41-2107-2990-D51F-6E8929B018EF,Caledon,"nisl arcu iaculis enim, sit amet" Farrah Melton,vehicula.et@maurisutmi.ca,erat nonummy ultricies,"sodales purus,",Nulla,DF147200-5A5A-15B0-EE74-0FC700E02F53,A0642D77-AAC7-0729-E90A-9AABEDA2C9B5,C856ADF9-2C48-7AFD-0D72-60D979F26BDB,Varsenare,magnis dis parturient Blair Cummings,non@sitametnulla.com,quis accumsan,"Sed pharetra,",Curae;,BBF5603C-EC73-0FF2-A92D-AEA4984A70BD,A6E5BC04-F87F-9152-E58E-FB1D851DE58F,1ADC6FD2-7BFF-B19B-7D85-97E8B71AAF31,Jedburgh,sapien molestie orci tincidunt adipiscing. Adam Mclaughlin,Maecenas.malesuada@Vestibulumut.co.uk,"ultrices sit amet, risus.",urna suscipit,ut,4FB798A8-6CC9-7709-2308-FD2EEAD07590,1D5D9ACB-14DA-9F6F-A49A-873A0FA726BE,A0C2ADED-FDE7-B7B1-7A3A-88669B8148A5,Pau,venenatis Gregory Russell,faucibus@Duisgravida.ca,mi. Duis risus,vulputate ullamcorper,in lobortis,77E50AFF-A531-095B-1198-051ED601031E,6B557381-1BB9-EC7C-F1BF-08F1747FE6C1,FF3A6A94-5AB3-D630-F795-C5E4D16825C9,Augusta,in Donovan Carter,lectus.Cum.sociis@arcuSed.edu,a tortor. Nunc,lobortis tellus,mattis,FD39F277-7D01-86FF-9AD8-DED5DD1CA67F,453A0D89-BAA1-CCD6-E621-42C5543B2124,638B7871-EEDA-61DC-7617-DA0E418758C2,Sigillo,"nibh enim, gravida sit amet, dapibus id, blandit at," Genevieve Sullivan,Nulla.tincidunt.neque@ridiculusmus.net,cubilia Curae; Phasellus,pede ac,"hendrerit a,",BF705C5A-532E-19B2-25FB-9734BE622768,7F47EAAB-BA4C-74E1-4EFE-788E599A673E,B46D3DCF-1935-9C90-30F2-7DEB9B6EF27C,Huelva,Nam tempor diam dictum sapien. Aenean massa. Integer Addison Hickman,congue@Ut.co.uk,Aliquam,ac mattis,ante bibendum,394B16CA-4DAA-0B2B-F2C9-E86CA86B49DC,FC689B22-F464-9F75-0C35-78D6CD7BA134,9BA9419E-3D97-21C2-7D9D-02B6EED98A10,W̦rgl,"erat, in consectetuer ipsum nunc" Tarik Tillman,eget@lectus.org,fringilla cursus,morbi tristique,dignissim. Maecenas,2B917A1B-552C-5B11-4E26-15B69677AC62,6F27188A-E0F2-B3EC-4343-D97346CC52B4,7F3D11FA-1DF1-850D-1432-BCD1D98291A5,Nivelles,quam vel sapien imperdiet ornare. In faucibus. Morbi vehicula. Zenia Baird,urna@Innecorci.co.uk,adipiscing elit. Etiam,Donec tincidunt.,"felis,",C11DC601-C76E-201B-E3F6-A3CC3524CAC0,D6952DE1-1F7D-4DF9-D18D-78D2CC8EEFEA,7B71D793-DBF3-573E-6F67-E75E22997561,K_nigs Wusterhausen,ornare. In faucibus. Morbi vehicula. Pellentesque Scarlet Conrad,tincidunt.congue.turpis@ipsum.co.uk,in lobortis,euismod est,"sit amet,",1808E3F8-7889-2AFD-A874-C2AB0FB14D70,FA2AC9AE-450F-3D0D-017B-AB9BDBD78E08,1873A457-0160-66DE-86DB-B32285DFEB21,Minna,est Alec Marks,sed.consequat.auctor@iaculisquis.ca,neque,imperdiet ornare.,vitae purus,7A21235A-FD01-1CC3-0097-336F3EE01665,F0B6A840-6211-BE49-8401-756D0BD5F7AB,8A1FB112-D60F-641C-6083-4B21B19B08C5,Cork,eu sem. Pellentesque ut ipsum ac mi Chelsea Donaldson,risus@Duis.edu,tellus,"sed, hendrerit",vehicula aliquet,240C7A94-B919-4970-602D-58861F386015,F668725C-23A4-6422-856F-4CC04C2D31AC,17252A7E-4C71-F168-603E-2691CF1608E7,Weymouth,ultricies sem magna Kamal Herman,lorem.sit@lectuspede.com,"magnis dis parturient montes,","a, malesuada",sed,00D29580-A14E-4821-075F-6144841D8E1C,CD4D4D85-621A-A57D-A716-4DD3D2E956EF,D0135C4D-8810-E1DF-4970-E697795A2E72,Liverpool,tempus mauris erat eget ipsum. Suspendisse sagittis. Aurelia Gross,sem.ut.dolor@eratnonummyultricies.net,faucibus,Donec dignissim,Nam,50D4BB83-C1F3-2EE3-E608-78731C31C9D2,C43A5C27-0659-FC1E-FD2C-56AC0CCEACA0,845A797C-A809-742F-A65D-4AF99697972C,Estevan,pede. Cras vulputate Kaseem Cox,velit@eu.ca,"sapien, cursus in, hendrerit",ut lacus.,"posuere, enim",0D919D9F-8B89-8DD2-CFEA-CCF512EAC600,2902C296-4DC3-E13B-0EB7-9EB9615405A4,D84DE1D3-E14B-D2C4-2330-1C8D19093DE1,Overland Park,Ut sagittis lobortis mauris. Suspendisse aliquet Cassady Decker,a.feugiat@ipsumCurabiturconsequat.org,vel,Morbi quis,Fusce mollis.,4C3630F8-84A3-2192-D37E-922C485DF271,D7452EA9-117D-2FE5-C6D9-077A1C71053B,0F5CBFD5-102E-25CA-D8F3-E5BA48B2838F,Sta_furt,eget Danielle Howard,mus.Aenean@Aliquamnec.org,aliquet magna,"eu, eleifend",vitae,75090114-A2EC-5A24-B953-98660ADF266E,6DF76F2F-C8B0-1238-8D6F-DAC7FE95B083,225DABDC-07FA-C9BD-3562-24EAC21350CF,Broechem,"et, lacinia vitae, sodales at, velit." Elijah Johnson,molestie.orci.tincidunt@euismodmauris.co.uk,vitae diam.,tempus mauris,"consequat auctor,",4F4437F4-7331-F34A-6ABF-5BD75F2F310B,A429D565-90E6-F21A-E6B1-C02952607A40,4EBB59B5-EB82-BDA4-C6D1-EAFBBD157875,Yaxley,"lacinia mattis. Integer eu lacus. Quisque imperdiet, erat nonummy" Yvette Franks,est.Nunc@Duisami.com,"faucibus leo,","eu, placerat",Pellentesque,E5D648EE-0204-D32C-D628-8F9BC03B97D3,768A8DF4-448C-140F-A6AD-DEE924CAF607,076BFB89-DDDA-D051-36A0-34884F725B3F,Jọo Pessoa,"accumsan laoreet ipsum. Curabitur consequat, lectus sit amet luctus vulputate," Garrison Finch,orci.in@afacilisis.net,Nunc,"vitae, erat.",scelerisque mollis.,0534661D-5368-19E6-6B55-C7AC42072D65,1EF7E457-D20A-D1F9-FF3A-391C733919E9,4FF8F344-696C-FC58-28F4-A8D511C52043,Villers-Poterie,nonummy ipsum non Lunea Underwood,tempor.diam@in.com,Proin vel arcu eu,Proin nisl,diam.,8E819261-ADC2-6D4B-354B-9A401DE418B5,743ABBD6-DEBD-1AEA-B3BC-CF4B78AF901A,D3265D5C-D954-DC73-F033-6AE0265CB847,Gallicchio,"elementum, lorem ut aliquam" Armand Klein,arcu.Vivamus@vitaerisusDuis.net,orci luctus et ultrices,lorem ac,nunc,9AE8CD74-6E82-91AD-E3E1-B263B45B8855,2AB9A671-1EBE-2824-122A-940FF8A3F3A8,30614602-1F6F-C5D8-EE2B-C75120191C42,Dingwall,eget mollis lectus pede Steel Burgess,dolor@pedenecante.net,nec urna,cursus. Integer,ultricies,4BE6FF80-6D87-1B1F-0135-FD3557F877E9,D659D229-C4E7-F21E-945E-D3DEBA281143,59622BB7-C7BF-8D5E-470C-B9805EB9779C,Richmond,"sed dolor. Fusce mi lorem," Tallulah Wiley,ultrices.sit@velit.net,ultrices,augue porttitor,arcu.,7AE904D1-0755-E725-ED6A-0354C15F4C91,988EED40-51A3-F313-6346-8390BB78ECE6,F1E2B64A-AF19-8EC9-10C2-6897C2544D02,Burns Lake,"vitae, orci. Phasellus" Leo Slater,sodales.nisi@Donecatarcu.co.uk,non ante bibendum ullamcorper.,Proin vel,consectetuer,2DB9FDFF-EED7-7EF8-0D17-D9A1DF70FCC7,D4C812F3-0CD8-2091-B299-C15A61D75471,61FBE6C6-F531-E4ED-68AD-39906502856A,Las Vegas,Mauris Zane Shelton,,felis. Nulla tempor augue,"at, libero.","id,",B105DA90-60E6-4251-9FE7-5116EB818AB4,829444B3-100F-53E9-71A6-A760D48B86D8,10BE1185-03CF-F9BD-440D-93E39510D81E,Pointe-aux-Trembles,nascetur ridiculus mus. Aenean eget magna. Kadeem Vega,neque.non.quam@duisemper.edu,nulla.,Vivamus non,"in,",D2C2757B-5BC3-62DA-276F-18752F2BB57D,6B3E0EA8-BC85-8761-E097-1FD600DEC81C,ACA78880-236D-8821-ABA4-DFA2F453050F,Rotterdam,"pretium et, rutrum non, hendrerit id, ante. Nunc mauris sapien," Dara Munoz,Donec@nisi.co.uk,iaculis odio. Nam,"quam, elementum",Proin non,9955AB46-0541-3280-97EB-7269F8C8CDA1,0F28DDFD-D137-B7E5-8499-BBEC033089DB,9EE33F9D-9F1D-C0FB-4527-A6FA0E713035,Laino Castello,"mi felis, adipiscing fringilla, porttitor vulputate, posuere vulputate, lacus. Cras" Britanni Castro,,ante lectus convallis,Cum sociis,netus et,1C268861-B6B8-6B4F-0E8A-E32935A4B9EE,BCAAF060-9B45-72C9-E54D-461852404ACD,01A4F9C8-0448-FD1B-57C3-F0E3AD61D9AE,Ottawa,rhoncus. Nullam velit Amery Guy,ligula.consectetuer@Duiselementum.net,vel arcu.,tortor. Integer,"sit amet,",4F26FF03-932C-32C5-B83B-281031B9732D,8A34A5F7-1879-2599-21E1-9A917491BE93,FBAD6E31-41B3-D192-8B2A-0CAFBBEC0CA1,Coventry,semper cursus. Integer mollis. Integer tincidunt aliquam Kelsey Boone,Aliquam.erat@arcuiaculis.co.uk,ac mi,lectus justo,diam vel,B141D616-D4A8-D6EC-A08D-1CD873A8A504,2BD7A5FE-86F9-DBD9-24E8-081DAEF1DFE2,2C4B83B3-F977-4105-B967-5EAC0A589380,Campotosto,"risus. In mi pede, nonummy ut, molestie" Fatima Kramer,,nisi sem,orci luctus,diam eu,66448BBE-D8C0-6BA4-4D01-13909ECB3798,997041BB-9EF3-FED4-72B1-B725A56BE02B,DBE25AFA-F7AB-5082-C507-7AF8DFEF6094,Bajardo,ipsum primis in faucibus orci luctus Jakeem Norris,,Proin mi. Aliquam,lobortis ultrices.,Donec non,A2DCAE82-10BE-4340-5D72-2A3BBEC45563,D7FD2555-D316-60F5-6A38-1587273BDDB8,FCBC5334-8D70-4780-DBE5-48463207D073,Aylesbury,sem magna nec quam. Curabitur vel lectus. Cum sociis Whilemina Reeves,eget.nisi.dictum@musDonecdignissim.org,nisl. Maecenas,semper. Nam,magnis dis,A8593B1A-2D01-2CF3-BC31-33D62E3AE375,B5E04355-79FC-7B8A-5911-4FE80CD916A9,498E0B24-7CB6-3681-9F60-C812ADFC89AA,Ghislarengo,purus Summer Rodriguez,risus@aliquetmagna.net,"adipiscing elit. Aliquam auctor,",et tristique,pulvinar,F5B3A17B-90FB-5E75-41FA-7337CC5A82A0,464CFD0B-1AEB-94DD-AA83-B90E6F68D15A,8DE52DE4-CD68-25E3-46F6-D24A293B687D,Waitakere,"cursus et," Stephen Owen,,mauris a nunc.,sagittis semper.,Sed nunc,DC8DAC04-79C2-AC11-B1AB-26E193558D7B,5B2F0ABA-3D95-F1CE-3E97-9A458EB1EAFE,91FF7C0B-3066-C21D-FE90-C8C4DBCF2B30,Varendonk,"risus," Leo Hernandez,massa.rutrum.magna@euismod.net,eu turpis. Nulla,dictum magna.,tincidunt,1EDFA44A-2FBC-2ABE-A80F-D9F010E13964,98C04402-FB96-4FC0-2C24-FB9BC1FC41A2,9BE16A6C-8B95-AE2A-97E2-8C7B07241A40,Somma Lombardo,mollis. Duis sit amet Francis Chambers,Cras@magnased.com,orci. Ut,aliquet. Phasellus,"ligula elit,",5BE6CD9A-76E8-3C8B-ED48-290C0D09A4DF,6E38DD9C-A362-C9E6-95C1-1257EC9C09E1,AD659302-F2F5-85F3-4612-0F1A32500314,Rocca Santo Stefano,Cum sociis natoque penatibus et Omar England,,"sed,",Pellentesque tincidunt,at,D7C96D4D-65EA-657E-9127-48A0E4940C91,5D4CA56E-3331-99B6-37F1-0646B39270BF,785B5890-2D50-EBA4-919D-EEE8690D7B4F,Solre-Saint-G_ry,odio vel est tempor Blaine Mckay,ornare.lectus@Praesent.net,"nulla ante,",dui. Cras,amet diam,6D0ED7A6-C785-A640-1893-78F4B977E649,9C665A0D-B8B8-6AFE-CE55-1F4F184DBC99,E0020FEF-FADD-3640-E3DD-9EDDE92EFCF0,Leugnies,purus mauris a nunc. In at pede. Cras vulputate velit Rudyard Cannon,volutpat.Nulla@Sed.org,dolor.,"erat, in","Integer vulputate,",5CE23AB9-D4A8-2811-D675-94372EC48F5B,C3E4F5D5-EFB2-AA6C-AC1D-931A77604FB1,032579DC-DD66-DD75-004D-237A955CC885,Bragan̤a,non nisi. Aenean eget metus. In nec Kermit White,in.consectetuer.ipsum@eliteratvitae.ca,nisi. Cum sociis natoque,sit amet,eros.,8A774B28-51C2-F721-5A98-EBE7D78691B3,E12A6D39-7608-D53D-FB2B-1F73CD216A6B,3F25A153-3D73-F6D1-C250-0E138DDBF803,Auxerre,vehicula risus. Nulla eget metus Ian Welch,nec@famesacturpis.edu,"sed consequat auctor,",Donec tincidunt.,"consectetuer, cursus",C816D208-D120-8542-9B3A-210FC17EB8CB,CCFCE8D5-317B-5FF3-1D43-A17E2CF8F5E2,F7281F4D-B42A-BCD1-E294-CE73FD3F96D8,Jou̩-l̬s-Tours,gravida. Aliquam Cade Jimenez,ac.fermentum@nibh.org,Nulla eu neque,varius. Nam,nunc.,38D39394-2416-2DB7-AD7A-8F26DF00BAA5,A93A5E84-1CA4-44BE-BCDD-FA63B8245EED,CA1E2495-9CA9-1118-6CFA-DF2D76D4715A,Pi_trebais,"ante blandit viverra. Donec tempus, lorem fringilla ornare placerat, orci" Melanie Brooks,magna.Lorem.ipsum@tellusjusto.ca,urna,"facilisis non,",feugiat metus,D8951F6B-483F-5C7E-1D67-FF8DE47AC9F8,0E7CEE4D-D436-4462-E1F5-417424B4354E,8E5BB87B-2AF4-3ADE-DA44-CDA19423C6C4,Juneau,"mi tempor lorem, eget mollis lectus pede et" Chava Sweet,porttitor@magnaSuspendissetristique.org,sit,Vestibulum ante,pharetra,E973DD5F-7668-BEFD-15FD-ED9AFD7CC8EC,FD2836C2-6B5B-03D8-89C0-2755EE935F94,CFC748C9-2432-7D79-69BD-3CBDF9253984,Huntsville,scelerisque dui. Suspendisse ac metus vitae Tallulah Boyd,fermentum@sodaleseliterat.net,Cras dolor,"congue a,",leo elementum,1EB81F77-71F9-9873-A8BA-E0C254778865,93F2F152-FD85-074D-9D8B-A15C42FA6E72,4637204A-98CA-1A3A-BAD1-518BABAABD09,Columbus,interdum. Samuel Bonner,turpis.egestas.Aliquam@torquentper.net,risus. Nulla eget metus,tristique senectus,ac,922EA557-5322-B04A-C241-90644FD36264,83B8CDA1-B053-7065-65CB-B27BF6B2558D,32706292-BB63-A819-4B86-CBE074768D6A,Moio Alcantara,"dis parturient montes, nascetur ridiculus mus. Proin vel" Fitzgerald Whitfield,vel@Quisque.net,orci. Donec nibh. Quisque,Vestibulum accumsan,eu,409D1A89-AF8E-B4F1-E406-0456D7797D27,1F8AF229-1E01-39C4-14D6-38BDBFA38CDC,5E711161-4B63-6F0B-EF92-73F18FD2BF69,Baracaldo,tempor bibendum. Donec Declan Cooke,Proin@Duissitamet.co.uk,"vel, vulputate eu,",Nulla eget,interdum.,CAB539F1-030D-AA34-4AE4-107493E22C06,6E30C2A3-2C11-7A47-1434-EAC857226F21,53789B1F-C8D2-7F61-8B2E-5C663436509B,Eksaarde,"tincidunt, neque vitae semper egestas, urna justo faucibus lectus, a" Buckminster Flores,euismod.in@dolorQuisque.org,"Duis risus odio,","cursus a,",quis,E3904B3D-A3D8-0E48-B608-E5FFA0F306A4,92635116-5E4F-93A0-99FD-BDE58F70C537,13917349-B53E-D81C-0D43-E87496EE50C7,Burns Lake,Donec sollicitudin adipiscing Inez Hatfield,venenatis.vel@necante.ca,"sed, facilisis vitae, orci.",sem mollis,hendrerit. Donec,BA0657D5-964D-44C7-490F-AF0B5C2F0831,81C88D41-74AF-4BB3-2795-8026ECCDDD0D,A86EE5A4-D3F5-3D9B-68B3-595974C301BB,Woodlands County,lobortis ultrices. Vivamus Erin Dickerson,felis.adipiscing@ullamcorperDuis.com,commodo auctor,consectetuer mauris,nonummy ipsum,706D596E-C579-384E-E66E-4CE6BB76D8FA,7E6DC3D8-F268-6FFB-3878-0A210ECEC287,8D7460C0-3BE3-3A23-5273-1BB4719311AF,Villers-la-Bonne-Eau,Class aptent taciti Kaitlin Barry,a@vel.ca,"enim, sit amet ornare",molestie tellus.,Cras eu,522D4F84-AF3A-8CEA-EAA6-7BADF313967D,8C31FA68-8A5D-F2A1-4B33-D7EBCB68DF68,16A38420-4D40-41FE-DC36-51B7C69C73CE,Esslingen,"iaculis, lacus pede sagittis augue, eu tempor erat neque non" Mechelle Cole,non@eu.ca,ligula. Donec luctus,vitae erat,id,99A8495B-E0C0-A261-4C97-A9678248533C,69CF987C-804E-3BEE-DB90-62CDC05DCD9C,53BB8A4D-AD9E-CBDE-80E6-09342C677D7B,Priolo Gargallo,"facilisis vitae, orci. Phasellus dapibus" Hilda Lawson,nunc.sit.amet@Cras.ca,dis parturient,"montes, nascetur",sodales nisi,DFA23639-1535-1681-B4D4-CEB6D7480617,5ABB6DB5-3F7E-F1A9-A73A-35DF06328B5A,5A48C838-1DF6-87B1-0093-E15A10E6B0FD,Ahmadpur East,"lacus. Quisque purus sapien," Maxine Bolton,id@id.com,adipiscing elit. Curabitur,Phasellus dolor,"nec,",4B4AB3CF-9429-25C6-2044-49B7CF1040B8,04FBF4ED-0B4D-0ECA-B1FC-C018099B80AE,CFEDE99F-26FA-0110-0C7D-932CEE400F90,Moose Jaw,"lorem fringilla ornare placerat, orci lacus vestibulum lorem, sit" Barclay Barry,velit.eu@eutellusPhasellus.org,non,metus. In,magna.,47972695-2E8D-971F-240B-2B56DD030F54,DDFC7836-599E-F3AD-DE18-6006B8AE867A,118C0A30-B7A1-92D9-C6D9-3788672350AD,Penna in Teverina,nunc sed libero. Proin sed turpis nec mauris blandit Heather Walker,luctus.aliquet@nunc.co.uk,ipsum.,lobortis mauris.,facilisis,782B7AF3-E24A-E73D-CEAC-ABE1D0011C58,2C1EC1E8-A9E6-FBC9-4DB7-4A080A111606,B0CFE4BD-C2E4-AFF4-7ACB-116B8DD63CA5,Huissen,arcu. Nunc mauris. Morbi non sapien molestie orci tincidunt Barclay Hooper,dolor@tempus.edu,amet ultricies sem magna,"a, scelerisque","lacinia vitae,",4E072253-EE38-D56D-AFFE-61E1D515D8A2,AD1243B7-BC39-1A5A-4D18-24510193C4C1,694933FE-0C09-ECB8-D0A5-1E98DAECA1BD,Morrinsville,"sed, facilisis vitae, orci. Phasellus dapibus quam quis diam. Pellentesque" Aphrodite Hines,nibh@ornare.net,sed dictum,nec tempus,non enim,3BC6DE34-FECB-CDA4-45C6-A0D46F73E8E5,3BFE2693-4384-8625-2299-3DBBCF35AF12,08719A17-AC36-A0B2-A47D-8B6E810169A7,Overmere,quam. Curabitur vel lectus. Kane Hale,amet.consectetuer.adipiscing@sit.edu,nascetur ridiculus,"Nunc ullamcorper,",diam,9FCADD4B-DC32-5EEB-5E04-EFA556DF3DEA,94A64883-7844-FA11-5D91-049C7E13AEF1,71747757-36E2-2B71-991E-66CBFE19168A,G_rouville,neque. Sed eget \ No newline at end of file diff --git a/docs/manual/user-management/README.md b/docs/manual/user-management/README.md new file mode 100644 index 0000000000..031409d901 --- /dev/null +++ b/docs/manual/user-management/README.md @@ -0,0 +1,90 @@ +--- +currentMenu: user-management +--- + +# User Management + +
+ +Snipe-IT comes with ability to manage users within the system. + +## User Throttling / Unsuspending Users + +If a user locks themselves out by attempting and failing to login too many times (default is 5 failed attempts), they will be locked out of the system for 15 minutes. If you need to unlock them before the 15 minutes is up, you can manually unsuspend them by going to the People section, searching for their name, and then clicking the unsuspend icon. + +![Unsuspend](/img/unsuspend-user.png) + +----- + +##Permissions + + +| Ability | Super User | Admin | Reporter | User | +| ------------- | -----------|-------|----------|------| +|Create Companies|Yes |Yes |No |No | +|Delete Companies|Yes |Yes |No |No | +|Create Asset Models|Yes |Yes |No |No | +|Delete Asset Models|Yes |Yes |No |No | +|Create Asset Categories|Yes |Yes |No |No | +|Delete Asset Categories|Yes |Yes |No |No | +|Create Manufacturer|Yes |Yes |No |No | +|Delete Manufacturer|Yes |Yes |No |No | +|Create Suppliers|Yes |Yes |No |No | +|Delete Suppliers|Yes |Yes |No |No | +|Create Status Labels|Yes |Yes |No |No | +|Delete Status Labels|Yes |Yes |No |No | +|Create Asset Depreciation|Yes|Yes |No |No | +|Delete Asset Depreciation|Yes|Yes |No |No | +|Create Locations|Yes |Yes |No |No | +|Delete Locations|Yes |Yes |No |No | +|Create Groups |Yes |Yes |No |No | +|Delete Groups |Yes |Yes |No |No | +|Take Backup |Yes |No |No |No | +|Delete Backup |Yes |No |No |No | +|Edit System Settings|Yes |Yes |No |No | +|Create Users |Yes |Yes |No |No | +|Remove Users |Yes |No |No |No | +|Create Assets |Yes |Yes |No |No | +|Edit Super Users|Yes |Yes |No |No | +|Unlock Users |Yes |Yes |No |No | +|Edit Users Permissions|Yes |Yes |No |No | +|View Items Assigned to User|Yes|Yes |No |No | +|Request Assets |No |No |No |Yes | +|Generate Reports| Yes |Yes |Yes |No | + + +----- + +## Optional: LDAP Configuration + +**Note: You must have the `php-ldap` extension installed for LDAP integration to work.** + +To set up your Snipe-IT installation to be able to use LDAP for user login and import, go to `Admin > Settings` and scroll down to the LDAP settings sections. + +If you don't have an LDAP server (or don't wish to import your users, or allow them to login using their LDAP credentials), you can skip this step. + +The LDAP functionality will import any users in your LDAP/Active Directory, but will leave existing users untouched. + +| Option | Example | Notes | Required | +| ------------- | ------------- | +|LDAP Server|`ldap://ldap.example.com`|The URL of the LDAP server.| Yes| +|LDAP Bind Username|`cn=read-only-admin,dc=example,dc=com`|Username to use to connect authenticate to LDAP.| Yes | +|LDAP Bind Password|`password`|Password to use when authenticating to LDAP.| Yes| +|Base Bind DN|`dc=example,dc=com`|The base where the search for users will be executed.|Yes| +|LDAP Filter|`&(cn=*)`|The search filter for the LDAP query.| Yes| +|Username Field|`uid`|The name of the field in your LDAP that you want to use for Snipe-IT username. |Yes| +|Last Name|`sn`|The name of the field in your LDAP to use for last name. This is often `sn` (for surname)|Yes| +|LDAP First Name|`cn`|The name of the field in your LDAP to use for first name.|Yes| +|LDAP Authentication query|`uid="`|The LDAP query we should use to search your LDAP users. (This is usually `samaccountname=` in Active Directory, `uid="` in non-AD LDAP.)|Yes| +|LDAP Version|`3`|Version of LDAP. This is usually going to be `3`|Yes| +|LDAP Active Flag|`active`|Only necessary if you use a field in LDAP to indicate if the user is active. Can otherwise be left blank.|No| +|LDAP Employee Number| |Only necessary if you use a field in LDAP to store an employee number. Can otherwise be left blank.|No| +|LDAP Email|`mail`|LDAP field that should map to an email address for the user|Yes| + +**Note: In most cases, all attribute values you enter should be all lowercase.** + +Once your settings are entered, make sure you check the `LDAP Integration` checkbox to enable LDAP authentication. + +### Example Settings + +We use a public LDAP server by Forumsys to test LDAP functionality. To test using this server, use the LDAP Server `ldap://ldap.forumsys.com`. diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000000..1e35a18c65 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,28 @@ +--- +currentMenu: requirements +--- + +# System Requirements + +The requirements for Snipe-IT are fairly standard for a modern web server, and most servers will have most or all of these components already installed. If for some reason you don't have them installed, they are relatively easy to add. + +## General System Requirements + +- PHP 5.4 or later: [](http://php.net/manual/en/install.unix.debian.php) [](http://www.microsoft.com/web/gallery/install.aspx?appid=PHP54) +- PHP Extensions: MCrypt, Fileinfo, php-pdo, php-mysql, php-mbstring, php-curl +- MySQL or MariaDB +- SSH access to the server (if using Linux) +- GD Library (>=2.0) or Imagick PHP extension (>=6.3.8) +- php-ldap extension (only if using LDAP) + +## Requirements Specific to Linux/OSX +- Mod Rewrite + +## Requirements Specific to Windows Server + +- IIS +- IIS URL Rewrite +- MariaDB 10.0.14 for Windows [64-bit](https://downloads.mariadb.org/interstitial/mariadb-10.0.14/winx64-packages/mariadb-10.0.14-winx64.msi/from/http%3A//mirror.aarnet.edu.au/pub/MariaDB) | [32-bit](https://downloads.mariadb.org/interstitial/mariadb-10.0.14/win32-packages/mariadb-10.0.14-win32.msi/from/http%3A//mirror.aarnet.edu.au/pub/MariaDB) +- [PHP Manager for IIS](http://phpmanager.codeplex.com/) (makes managing PHP on IIS much easier) +- [Composer install with the shell menus](https://getcomposer.org/Composer-Setup.exe) +- [Notepad++](http://www.notepad-plus-plus.org/download/v6.6.6.html) for editing files diff --git a/docs/search.md b/docs/search.md new file mode 100644 index 0000000000..651aa3be71 --- /dev/null +++ b/docs/search.md @@ -0,0 +1,8 @@ +--- +currentMenu: search +--- + +# Search Results + + +
diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000000..dfbbe99c9e --- /dev/null +++ b/docs/security.md @@ -0,0 +1,17 @@ +--- +currentMenu: security +--- + +# Some Notes on Security + +Snipe-IT was built with security in mind. We utilize bcrypt to handle passwords, which is an adaptive hash function based on the Blowfish symmetric block cipher cryptographic algorithm. Additionally, the software is designed in such a way to prevent brute forcing the password, with IP addresses and usernames locked out for 10 minutes after a specified number of login attempts. + +## Additional Security + +Although this is web-based software and must run on a web server, you may want to consider whether you actually need it accessible to the outside world. Running it on an internal network with ports closed to the outside world, or on AWS using a security group that prevents access from outside a selected static IP range (like your company network IP), may be something to consider. + +While most use cases won't be storing Personally Identifiable Information (PII), someone with the right motivation could gain useful knowledge about the number of employees, types of assets, etc you maintain. While this information in and of itself isn't harmful, it could be helpful to Bad Guys in a targeted attack, so you should consider whether you want to limit access to it via IP or network rules. + +Also, running Snipe-IT over SSL is not required, but a good idea. (Running everything ever over SSL is a good idea at this point.) + +There are some optional configuration options that you can enable if you run Snipe-IT over HTTPS, such as enabling HTTPS-only cookies, and setting your `.htaccess` to redirect to the HTTPS version. diff --git a/docs/translations.md b/docs/translations.md new file mode 100644 index 0000000000..07f2e381c3 --- /dev/null +++ b/docs/translations.md @@ -0,0 +1,12 @@ +--- +currentMenu: translations +--- +# Translations! + +If you're not a coder but want to give back to the project and you're fluent in other languages, consider helping out with the translations. We use the [CrowdIn](https://crowdin.com) localization platform to manage translations, and it makes it super-simple for you to add translations to the project without messing with code. Check out [the Snipe-IT CrowdIn translation project here](https://crowdin.com/project/snipe-it/). + +We currently have English, Spanish, German, Korean and Brazilian Portuguese completed, and are looking for more! + +If you'd like to translate Snipe-IT into a language that we don't currently offer, simply let us know via the CrowdIn platform or by [creating an issue on Github](https://github.com/snipe/snipe-it/issues) and we'll get that set up for you. + +**Please do not submit pull requests with language files directly to the repository. The CrowdIn platform allows us to make sure all of language files are in sync between versions and releases, so we only accept translations through the CrowdIn platform.** diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000000..980a75910c --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,32 @@ +--- +currentMenu: upgrading +--- + +# Upgrading +Updating Snipe-IT should be pretty straightforward. Simply pull down the newest release, copy the files over, and run whatever commands the release notes specify. Your configuration files won’t be overwritten, since you had to copy them over from the example configs, and your version isn’t in version control. + +You may want to backup the `app/config/app.php` file however, as that one file will be overwritten. If you forget to back it up, it's not usually a big deal, just go back in after upgrading and set your timezone back to the one you had before. + +__Always backup your database and configuration files before upgrading.__ We try very hard to make sure that all database changes are non-destructive, but you should always backup beforehand anyway. You will never regret backing up your database. You may regret not doing so, so it’s just better to get into the habit. + +If you don’t plan on contributing code to Snipe-IT, you should always grab the latest stable release from the releases page, and avoid using the `develop` or `master` branches. + +Whenever you pull down a new version from master or develop, or when you grab the latest official release, make sure to run the following commands via command line: + +``` +php composer.phar install --no-dev --prefer-source +php composer.phar dump-autoload +php artisan migrate +``` + +(Developers should remove the `--no-dev` flag, so they have unit test frameworks and debugging tools.) + +Forgetting to run these commands can mean your DB might end up out of sync with the new files you just pulled, or you may have some funky cached autoloader values. + +It’s a good idea to get into the habit of running these every time you pull anything new down. If there are no database changes to migrate, it won't hurt anything to run migrations anyway, you’ll just see "Nothing to migrate". + +In some cases, it can help to delete the contents (just the contents, not the directories themselves) of `app/storage/cache` and `app/storage/views`. + +If you have any issues upgrading, check the [common issues](common-issues.html) page for a fix. If you don’t see your issue listed there, open an issue on Github and we’ll try to get you sorted out. Be sure to provide the information outlined in the [Getting Help](getting-help.html) section of this site so that we have the info we need to assist you. + +IMPORTANT: If you’re upgrading from `v.0.3.0-alpha` or earlier, make sure to update your hostname information in `bootstrap/start.php`, per the new requirements in Laravel 4.1.