InstallationUser's ManualReleasesHostedPro SupportAPI Reference

Docker

Note very loudly that additional Docker options should be set in the env file, and they require a restart!

Suggest Edits

❗️

NOTICE:

The ONLY docker image we support is snipe/snipe-it. If you grabbed a docker image from any other repo, you're kinda on your own, since we cannot be responsible for images we do not manage directly.

Docker is a very popular software containerization platform. While it's not difficult to use, it can be a little confusing for folks who are less familiar with containerization.

We'll attempt to walk you through a Docker setup here, but please see the Docker documentation for a more in-depth understanding of Docker fundamentals. If you don't know the implications of the steps you're taking here, you could potentially lose access to your data.

🚧

A NOTE FOR N00BS:

This Docker image uses some advanced concepts such as linking, storage volumes, and multiple images, so it may not be a good choice for learning Docker, however if you're willing to put some time into researching the concepts and background of Docker, we'll be happy to help you as best we can.

🚧

Any configuration changes in your docker-env file will require a container restart!

If you don't restart your Snipe-IT container, it won't pick up the new values. That's not a Snipe-IT thing, that's a docker thing.

The easiest way to get started with Snipe-IT on Docker is to use the Docker image we push to Docker Hub:

docker pull snipe/snipe-it

If you'd rather grab a specific version of Snipe-IT, use the tag for the release you'd like to use. For example, to use the 5.1.7 release, you would use:

docker pull snipe/snipe-it:v5.1.7

For a list of all available Docker version tags, check out the tags page on Dockerhub.

How to Get Up and Running

🚧

Options Have Changed From v2.x!

Please note some of the options have changed, and some new options are now required!

Docker's Environment Variables

Snipe-IT's Docker configuration requires many different environment variables in order to function correctly. To keep things simple, we try to centralize all of those settings in an environment file. If you are using a method other than the standard docker CLI to integrate Snipe-IT into your docker environment, then you will need to make sure to pass all of the below mentioned variables into your Snipe-IT environment.

The Snipe-IT env-file is a simple text file with some variables and values that your Snipe-IT installation needs, separated by = signs. These environment variables will also affect your MySQL configuration.

You can call this file anything you want, and put it wherever you like, just remember what you called it and where you put it, since you'll need to reference this file when you run your Docker containers, using the --env-file=<your_docker_env_file_name> argument. You'll see examples of this in the commands further down the page as you initialize your Docker container.

For the purposes of this documentation, we'll call our file my_env_file.

Your my_env_file is not the same .env file Snipe-IT uses directly, but the values you put in it are used to generate the .env file that Snipe-IT does use, so what you put in here matters.

❗️

Any Other .env Options You want to Set Should Be Set Here!

Any additional parameters you set in your my_env_file will be automatically propagated into your running Snipe-IT environment.

So just because we don't list every single possible .env variable in the my_env_file doesn't mean we don't support it - please set the option in your my_env_file and launch a new container to pick up your latest changes!

Your my_env_file should look like this:

# 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
[email protected]
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
APP_ENV=production
APP_DEBUG=false
APP_KEY=<<Fill in Later!>>
APP_URL=http://127.0.0.1:<<YOUR_PORT_NUMBER>>
APP_TIMEZONE=US/Pacific
APP_LOCALE=en
  
# Docker-specific variables
PHP_UPLOAD_LIMIT=100

Remember, if you're not using an .env-file, you will have to pass all of these variables into your docker container when you launch it.

First get a MySQL container running. MySQL 5.6 or earlier are easiest.

docker run --name snipe-mysql --env-file=my_env_file --mount source=snipesql-vol,target=/var/lib/mysql -d -P mysql:5.6

If your my_env_file contains a MYSQL_USER, MYSQL_PASSWORD, and a MYSQL_DATABASE, then the MySQL container will automatically create that database and grant permissions to access it. If you're using an external database, or an already existing container, you'll have to create a database for Snipe-IT to use, and grant a user access to it - and put those credentials in your my_env_file.

The data for your MySQL container will live in the named volume snipesql-vol. Docker will create this volume for you if it does not exist already.

🚧

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)

Using a Standalone Database (not a container)

If you're using a separate, standalone database, you can specify the hostname as MYSQL_PORT_3306_TCP_ADDR. If your database runs on a different port, you can specify that with MYSQL_PORT_3306_TCP_PORT. You don't need to specify the MYSQL_ROOT_PASSWORD.

Thus, your config should look as follows:

# Mysql Parameters
MYSQL_PORT_3306_TCP_ADDR=XXX.XXX.XXX.XXX
MYSQL_PORT_3306_TCP_PORT=3306

MYSQL_DATABASE=snipe_it
MYSQL_USER=snipe_it_db_user
MYSQL_PASSWORD=snipe_it_db_user_password

📘

NOTE:

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, we'll need to generate an app key. If you already have a Snipe-IT container running, make note of the APP_KEY. In older versions of Snipe-IT, it was stored in app/config/production/app.php.

Otherwise, you can easily generate a new one, just run the container:

docker run --rm snipe/snipe-it

Or to run with your specified version:

docker run --rm snipe/snipe-it:v4.1.13

The output should look like:

Please re-run this container with an environment variable $APP_KEY
An example APP_KEY you could use is: 
base64:D5oGA+zhFSVA3VwuoZoQ21RAcwBtJv/RGiqOcZ7BUvI=

Add that APP_KEY to your docker env-file (we left a placeholder for it in your starting docker env file, above). Make sure to include the base64: prefix if it is given! If you're not using an env-file, you will need to pass the APP_KEY as an environment variable to your docker container.

You'll also need to decide which port number to 'expose' for the HTTP and HTTPS endpoints. Once you've selected one, make sure to set your APP_URL variable in your Docker env-file to reference it.

Finally, decide whether or not you want to have your Snipe-IT container manage SSL for you, or not.

As a side-note, if you're running boot2docker or docker-machine, you may need to prefix the port declarations below with an IP address - $(docker-machine ip default): or 123.45.78.89:

SSL disabled

Start your Snipe-IT container:

If you pulled the image with exact version number tag than you need apply here as well of course.

Start with the latest version:

docker run -d -p YOUR_PORT_NUMBER:80 --name="snipeit" --link snipe-mysql:mysql --env-file=my_env_file --mount source=snipe-vol,dst=/var/lib/snipeit snipe/snipe-it

The 'named volume' snipe-vol will be created if it does not already exist.

Version specific start:

docker run -d -p YOUR_PORT_NUMBER:80 --name="snipeit" --link snipe-mysql:mysql --env-file=my_env_file --mount source=snipe-vol,dst=/var/lib/snipeit snipe/snipe-it:v.4.1.13

SSL enabled

Start your Snipe-IT container - but be prepared to copy your SSL key and certificate to your storage volume. When you first launch the Snipe-IT container, the named volume snipe-vol will be created and initialized. You can use the docker cp command to copy your certificate data to the storage volume, at /var/lib/snipeit/ssl/snipeit-ssl.crt and /var/lib/snipeit/ssl/snipeit-ssl.key.

docker run -d -p YOUR_PORT_NUMBER:80 -p YOUR_SSL_PORT:443 --name="snipeit" --link snipe-mysql:mysql --mount source=snipe-vol,dst=/var/lib/snipeit --env-file=my_env_file snipe/snipe-it

Version specific start with SSL

docker run -d -p YOUR_PORT_NUMBER:80 -p YOUR_SSL_PORT:443 --name="snipeit" --link snipe-mysql:mysql --mount source=snipe-vol,dst=/var/lib/snipeit --env-file=my_env_file snipe/snipe-it:v4.1.13

Email, Management, Access

If you have a separate container running for email, you will also want a --link setting for email as well.

That's It!

You can now initialize the application and database by pointing your web browser to: http://your_ip:YOUR_PORT, which will automatically redirect you to the setup screen.

Updating Snipe-IT or MySQL

To upgrade your Snipe-IT installation, you should stop your old container, re-pull the latest Snipe-IT version, then launch the new container as before, but connecting to the same storage volume - named snipe-vol in our examples. You will have to rename your old container to be able to reuse the 'snipeit' name.

After that, you may need to run migrations using docker run snipeit php artisan migrate.

Once you're completely sure that everything on your new installation is working, you may delete the old Snipe-IT container.

To upgrade MySQL, stop your old container, pull whatever new version you want to switch to, and make sure to run your new container with the same named volume - we called it snipesql-vol in our examples.

ADVANCED docker usage

❗️

WARNING! Advanced users ONLY!

These are all advanced features of Docker. Please only use them if you are already extremely knowledgeable about how to use Docker.

Bind Mounts

Instead of using named volumes, as above, you may instead use a 'bind mount' to point to a local directory. This was an older method that Snipe-IT's docker integration used, but Docker no longer recommends it.

If you need that feature for whatever reason, you should pass the fully-qualified path (absolute path) instead of the named volume in the various above commands.

Specifically, the mount parameter in your command-lines should look something like this:

--mount source=/full/path/to/your/snipe-directory/,dst=/var/lib/snipeit

You may need to create various folders in that directory. See the Dockerfile and the /entrypoint.sh files for specific details.

Behind a SSL / HSTS reverse proxy

If your container is setup behind a trusted reverse proxy (such as nginx) and HSTS is active, you'll need to pass a few more parameters for Snipe-It to work. Add to your .env file at least the following lines:

APP_TRUSTED_PROXIES=REMOTE_ADDR
SECURE_COOKIES=true

For Development

You can build the snipe-it image using the Dockerfile at the root directory of Snipe-IT by doing this:

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:

docker run -d -v /Path/To/My/snipe-it/checkout:/var/www/html -P --name="snipeit" --link mysql:mysql snipeit

Then your local changes to the code will be reflected. You will have to re-run composer install -

docker exec -i -t snipeit composer install

And you may still need to generate the key with -

docker exec -i -t snipeit php artisan key:generate --env=production

While you're developing, you may need to occasionally run:

docker exec snipeit composer dump

To fix the autoloading cache (if, for example, your class names change, or you add new ones...)

Updated 7 months ago