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.
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 4.1.13 release, you would use:
docker pull snipe/snipe-it:v4.1.13
For a list of all available Docker version tags, check out the tags page on Dockerhub.
Options Have Changed From v2.x!
Please note some of the options have changed, and some new options are now required!
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.
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 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.
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
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
my_env_file contains a
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
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.
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)
In case you want an approach for installation based on a single command, the you can also use docker-compose to create your Snipe-IT environment.
First, you need to create a
version: '3' services: snipe-mysql: container_name: snipe-mysql image: mysql:5.6 env_file: - ./.env volumes: - snipesql-vol:/var/lib/mysql command: --default-authentication-plugin=mysql_native_password expose: - "3306" snipe-it: image: snipe/snipe-it env_file: - ./.env ports: - "3051:80" depends_on: - snipe-mysql volumes: snipesql-vol:
docker-compose.yml file references a .env file that is mostly similar to the previous env file that was presented in this documentation page.
The difference is that you need to let the Snipe-IT container know how to communicate with the container that has the database.
In order to do it, the
.env file should look something like this:
# Mysql Parameters MYSQL_PORT_3306_TCP_ADDR=snipe-mysql 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:80 APP_TIMEZONE=US/Pacific APP_LOCALE=en
You will need to follow the steps necessary to generate the API key for usage in this instance, and you can do so by accessing the shell inside the Snipe-IT container. You can do so with:
docker exec -it snipe-it-container-name sh
After this you will have shell access to the console and you can generate the app key in the root folder with:
php artisan key:generate
After this step, simply replace the
<<Fill in Later!>> in your
.env file with your actual app key and you are ready to launch the app.
And that's it for the setup with docker-compose.
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
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
If your Email solution requires its own container, start that container or service. Make sure to expose port 587 for mail submission, and use
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
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=
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
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
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
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
If you have a separate container running for email, you will also want a
--link setting for email as well.
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.
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.
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.
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.
mount parameter in your command-lines should look something like this:
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
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 snipe-it
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 2 months ago