Docker
Note very loudly that additional Docker options should be set in the env file, and they require a restart!
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 themy_env_file
doesn't mean we don't support it - please set the option in yourmy_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