Making README.md Docker Hub friendly.

This commit is contained in:
Ric Harvey
2015-01-28 11:47:13 +00:00
parent 4bab9195d4
commit dfcc9ff123

View File

@@ -1,47 +1,62 @@
## Introduction ## Introduction
This is a Dockerfile to build a container image for nginx and php-fpm, with the ability to pull website code from git. The container can also use environment variables to configure your web application using the templating detailed in the [special features](#special-features) section. This is a Dockerfile to build a container image for nginx and php-fpm, with the ability to pull website code from git. The container can also use environment variables to configure your web application using the templating detailed in the special features section.
## Version ## Version
- Mainline Version: **1.7.9** - Mainline Version: **1.7.9**
- Stable Version: **1.6.2** - Stable Version: **1.6.2**
- *Latest = Mainline Version* - *Latest = Mainline Version*
## Installation ## Installation
Pull the image from the docker index rather than downloading the git repo. This prevents you having to build the image on every docker host. Pull the image from the docker index rather than downloading the git repo. This prevents you having to build the image on every docker host.
```bash
```
docker pull richarvey/nginx-pfp-fpm:latest docker pull richarvey/nginx-pfp-fpm:latest
``` ```
To pull the Stable Version: To pull the Stable Version:
```bash
```
docker pull richarvey/nginx-pfp-fpm:stable docker pull richarvey/nginx-pfp-fpm:stable
``` ```
## Running ## Running
To simply run the container: To simply run the container:
```bash
```
sudo docker run --name nginx -p 8080:80 -d richarvey/nginx-php-fpm sudo docker run --name nginx -p 8080:80 -d richarvey/nginx-php-fpm
``` ```
You can then browse to http://<docker_host>:8080 to view the default install files. You can then browse to http://<docker_host>:8080 to view the default install files.
### Volumes ### Volumes
If you want to link to your web site directory on the docker host to the container run: If you want to link to your web site directory on the docker host to the container run:
```bash
```
sudo docker run --name nginx -p 8080:80 -v /your_code_directory:/usr/share/nginx/html -d richarvey/nginx-php-fpm sudo docker run --name nginx -p 8080:80 -v /your_code_directory:/usr/share/nginx/html -d richarvey/nginx-php-fpm
``` ```
### Pulling code from git ### Pulling code from git
One of the nice features of this container is its ability to pull code from a git repository with a couple of environmental variables passed at run time. One of the nice features of this container is its ability to pull code from a git repository with a couple of enviromental variables passed at run time.
**Note:** You need to have your SSH key that you use with git to enable the deployment. I recommend using a special deploy key per project to minimise the risk. **Note:** You need to have your SSH key that you use with git to enable the deployment. I recommend using a special deploy key per project to minimise the risk.
To run the container and pull code simply specify the GIT_REPO URL including *git@* and then make sure you have a folder on the docker host with your id_rsa key stored in it: To run the container and pull code simply specify the GIT_REPO URL including *git@* and then make sure you have a folder on the docker host with your id_rsa key stored in it:
```bash
```
sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm
``` ```
To pull a repository and specify a branch add the GIT_BRANCH environment variable: To pull a repository and specify a branch add the GIT_BRANCH environment variable:
```bash
```
sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'GIT_BRANCH=stage' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'GIT_BRANCH=stage' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm
``` ```
### Linking ### Linking
Linking to containers also exposes the linked container environment variables which is useful for [templating](#templating) and configuring web apps: Linking to containers also exposes the linked container environment variables which is useful for templating and configuring web apps.
Run MySQL container with some extra details: Run MySQL container with some extra details:
```bash
```
sudo docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=yayMySQL -e MYSQL_DATABASE=wordpress -e MYSQL_USER=wordpress_user -e MYSQL_PASSWORD=wordpress_password -d mysql sudo docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=yayMySQL -e MYSQL_DATABASE=wordpress -e MYSQL_USER=wordpress_user -e MYSQL_PASSWORD=wordpress_password -d mysql
``` ```
This exposes the following environment variables to the container when linked: This exposes the following environment variables to the container when linked:
``` ```
MYSQL_ENV_MYSQL_DATABASE=wordpress MYSQL_ENV_MYSQL_DATABASE=wordpress
MYSQL_ENV_MYSQL_ROOT_PASSWORD=yayMySQL MYSQL_ENV_MYSQL_ROOT_PASSWORD=yayMySQL
@@ -55,35 +70,47 @@ MYSQL_PORT_3306_TCP_PROTO=tcp
MYSQL_PORT_3306_TCP_ADDR=172.17.0.236 MYSQL_PORT_3306_TCP_ADDR=172.17.0.236
MYSQL_ENV_MYSQL_MAJOR=5.6 MYSQL_ENV_MYSQL_MAJOR=5.6
MYSQL_PORT=tcp://172.17.0.236:3306 MYSQL_PORT=tcp://172.17.0.236:3306
``` ```
To link the container launch like this: To link the container launch like this:
```bash ```
sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 --link some-mysql:mysql -d richarvey/nginx-php-fpm sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 --link some-mysql:mysql -d richarvey/nginx-php-fpm
``` ```
## Special Features ## Special Features
### Templating ### Templating
This container will automatically configure your web application if you template your code. For example if you are linking to MySQL like above, and you have a config.php file where you need to set the MySQL details include $$_MYSQL_ENV_MYSQL_DATABASE_$$ style template tags. Example: This container will automatically configure your web application if you template your code. For example if you are linking to MySQL like above, and you have a config.php file where you need to set the MySQL details include $$_MYSQL_ENV_MYSQL_DATABASE_$$ style template tags.
```php
Example:
```
<?php <?php
database_name = $$_MYSQL_ENV_MYSQL_DATABASE_$$; database_name = $$_MYSQL_ENV_MYSQL_DATABASE_$$;
database_host = $$_MYSQL_PORT_3306_TCP_ADDR_$$; database_host = $$_MYSQL_PORT_3306_TCP_ADDR_$$;
... ...
?> ?>
``` ```
### Using environment variables ### Using environment variables
If you want to link to an external MySQL DB and not using linking you can pass variables directly to the container that will be automatically configured by the container. If you want to link to an external MySQL DB and not using linking you can pass variables directly to the container that will be automatically configured by the container.
Example: Example:
```bash
```
sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'GIT_BRANCH=stage' -e 'MYSQL_HOST=host.x.y.z' -e 'MYSQL_USER=username' -e 'MYSQL_PASS=password' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm sudo docker run -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'GIT_BRANCH=stage' -e 'MYSQL_HOST=host.x.y.z' -e 'MYSQL_USER=username' -e 'MYSQL_PASS=password' -v /opt/ngddeploy/:/root/.ssh -p 8080:80 -d richarvey/nginx-php-fpm
``` ```
This will expose the following variables that can be used to template your code. This will expose the following variables that can be used to template your code.
``` ```
MYSQL_HOST=host.x.y.z MYSQL_HOST=host.x.y.z
MYSQL_USER=username MYSQL_USER=username
MYSQL_PASS=password MYSQL_PASS=password
``` ```
To use these variables in a template you'd do the following in your file: To use these variables in a template you'd do the following in your file:
```php
```
<?php <?php
database_host = $$_MYSQL_HOST_$$; database_host = $$_MYSQL_HOST_$$;
database_user = $$_MYSQL_USER_$$; database_user = $$_MYSQL_USER_$$;