From a47de47b1bc3a7114afbbaf42aae88c344432925 Mon Sep 17 00:00:00 2001 From: Ric Harvey Date: Tue, 9 Aug 2016 14:21:25 +0100 Subject: [PATCH] Update readme with new features and flags --- README.md | 82 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index fab963b..eb91c5f 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,14 @@ The Docker hub build can be found here: [https://registry.hub.docker.com/u/richa ## Building from source To build from source you need to clone the git repo and run docker build: ``` -git clone https://github.com/ngineered/nginx-php-fpm.git +git clone https://github.com/ngineered/nginx-php-fpm +.git docker build -t nginx-php-fpm:latest . ``` ## Pulling from Docker Hub -Pull the image from docker hub rather than downloading the git repo. This prevents you having to build the image on every docker host: ``` -docker pull richarvey/nginx-php-fpm:latest +docker pull richarvey/nginx-php-fpm ``` ## Running @@ -34,15 +34,17 @@ sudo docker run -d richarvey/nginx-php-fpm ``` You can then browse to ```http://:8080``` to view the default install files. To find your ```DOCKER_HOST``` use the ```docker inspect``` to get the IP address. -### Available Configuration Parameters +### Available Configuration Parameters The following flags are a list of all the currently supported options that can be changed by passing in the variables to docker with the -e flag. - - **GIT_REPO** : URL to the repository containing your source code + - **GIT_REPO** : URL to the repository containing your source code. If you are using a personal token, this is the https URL without https://, e.g github.com/project/ for ssh prepend with git@ e.g git@github.com:project.git - **GIT_BRANCH** : Select a specific branch (optional) - **GIT_EMAIL** : Set your email for code pushing (required for git to work) - **GIT_NAME** : Set your name for code pushing (required for git to work) - **SSH_KEY** : Private SSH deploy key for your repository base64 encoded (requires write permissions for pushing) + - **GIT_PERSONAL_TOKEN** : Personal access token for your git account (required for HTTPS git access) + - **GIT_USERNAME** : Git username for use with personal tokens. (required for HTTPS git access) - **WEBROOT** : Change the default webroot directory from `/var/www/html` to your own setting - **ERRORS** : Set to 1 to display PHP Errors in the browser - **HIDE_NGINX_HEADERS** : Disable by setting to 0, default behaviour is to hide nginx + php version in headers @@ -50,57 +52,99 @@ The following flags are a list of all the currently supported options that can b - **PHP_POST_MAX_SIZE** : Set a larger post_max_size, default is 100 Mb - **PHP_UPLOAD_MAX_FILESIZE** : Set a larger upload_max_filesize, default is 100 Mb - **DOMAIN** : Set domain name for Lets Encrypt scripts + - **RUN_SCRIPTS** : Set to 1 to execute scripts + ### Dynamically 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 environmental variables passed at run time. Please take a look at our recommended [repo layout guidelines](docs/repo_layout.md). -**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. +There are two methods of pulling code from git, you can either use a Personal Token (recommended method) or an SSH key. -### Preparing your SSH key -The container expects you pass it the __SSH_KEY__ variable with a **base64** encoded private key. First generate your key and then make sure to add it to github and give it write permissions if you want to be able to push code back out the container. Then run: +**Note:** We would recommend using a git personal token over an SSH key as it simplifies the set up process. To create a personal access token on Github follow this [guide](https://help.github.com/articles/creating-an-access-token-for-command-line-use/). + +#### Personal Access token + +You can pass the container your personal access token from your git account using the __GIT_PERSONAL_TOKEN__ flag. This token must be setup with the correct permissions in git in order to push and pull code. + +Since the access token acts as a password with limited access, the git push/pull uses HTTPS to authenticate. You will need to specify your __GIT_USERNAME__ and __GIT_PERSONAL_TOKEN__ variables to push and pull. You'll need to also have the __GIT_EMAIL__, __GIT_NAME__ and __GIT_REPO__ common variables defined. + +``` +docker run -d -e 'GIT_EMAIL=email_address' -e 'GIT_NAME=full_name' -e 'GIT_USERNAME=git_username' -e 'GIT_REPO=github.com/project' -e 'GIT_PERSONAL_TOKEN=' richarvey/nginx-php-fpm:latest +``` + +To pull a repository and specify a branch add the __GIT_BRANCH__ environment variable: +``` +docker run -d -e 'GIT_EMAIL=email_address' -e 'GIT_NAME=full_name' -e 'GIT_USERNAME=git_username' -e 'GIT_REPO=github.com/project' -e 'GIT_PERSONAL_TOKEN=' -e 'GIT_BRANCH=stage' richarvey/nginx-php-fpm:latest +``` +#### SSH keys + +##### Preparing your SSH key +The container has the option for you to pass it the __SSH_KEY__ variable with a **base64** encoded private key. First generate your key and then make sure to add it to github and give it write permissions if you want to be able to push code from the container. Then run: ``` base64 -w 0 /path_to_your_key ``` -**Note:** Copy the output be careful not to copy your prompt +**Note:** Copy the output, but be careful not to copy your prompt + +##### Running with SSH Keys To run the container and pull code simply specify the GIT_REPO URL including *git@* and then make sure you have also supplied your base64 version of your ssh deploy key: ``` -sudo docker run -d -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'SSH_KEY=BIG_LONG_BASE64_STRING_GOES_IN_HERE' richarvey/nginx-php-fpm +sudo docker run -d -e 'GIT_NAME=full_name' -e 'GIT_USERNAME=git_username' -e 'GIT_REPO=github.com/project' -e 'SSH_KEY=BIG_LONG_BASE64_STRING_GOES_IN_HERE' richarvey/nginx-php-fpm:latest ``` + To pull a repository and specify a branch add the GIT_BRANCH environment variable: ``` -sudo docker run -d -e 'GIT_REPO=git@git.ngd.io:ngineered/ngineered-website.git' -e 'GIT_BRANCH=stage' -e 'SSH_KEY=BIG_LONG_BASE64_STRING_GOES_IN_HERE' richarvey/nginx-php-fpm +sudo docker run -d -e 'GIT_NAME=full_name' -e 'GIT_USERNAME=git_username' -e 'GIT_REPO=github.com/project' -e 'SSH_KEY=BIG_LONG_BASE64_STRING_GOES_IN_HERE' -e 'GIT_BRANCH=stage' richarvey/nginx-php-fpm:latest ``` -### Enabling SSL or Special Nginx Configs -You can either map a local folder containing your configs to /etc/nginx or we recommend editing the files within __conf__ directory that are in the git repo, and then rebuilding the base image. + +### Scripting +There is often an occasion where you need to run a script on code to do a transformation once code lands in the container. For this reason we have developed scripting support. By including a scripts folder in your git repository and passing the __RUN_SCRIPTS=1__ flag to your command line the container will execute your scripts. Please see the [repo layout guidelines](docs/repo_layout.md) for more details on how to organise this. ### Lets Encrypt support (Experimental) +#### Enabling SSL or Special Nginx Configs +You can either map a local folder containing your configs to /etc/nginx or (recommended method) edit the files within the __conf__ directory in a copy of this git repo, and then rebuilding the base image. #### Setup -You can use Lets Encrypt to secure your container. Make sure you start the container ```DOMAIN, GIT_EMAIL``` and ```WEBROOT``` variables to enable this to work. Then run: +You can use Lets Encrypt to secure your container. Make sure you start the container with the ```DOMAIN, GIT_EMAIL``` and ```WEBROOT``` variables set to enable this functionality. Then run: ``` sudo docker exec -t /usr/bin/letsencrypt-setup ``` -Ensure your container is accessible on the ```DOMAIN``` you supply in order for this to work +Ensure your container is accessible on the ```DOMAIN``` you supplied in order for this to work #### Renewal Lets Encrypt certs expire every 90 days, to renew simply run: ``` sudo docker exec -t /usr/bin/letsencrypt-renew ``` + ## Special Git Features -You'll need some extra ENV vars to enable this feature. These are ```GIT_EMAIL``` and ```GIT_NAME```. This allows git to be set up correctly and allow the following commands to work. +Specify the ```GIT_EMAIL``` and ```GIT_NAME``` variables for this to work. They are used to set up git correctly and allow the following commands to work. + ### Push code to Git -To push code changes made within the container back to git simply run: +To push code changes made within the container back to git run: ``` sudo docker exec -t -i /usr/bin/push ``` + ### Pull code from Git (Refresh) -In order to refresh the code in a container and pull newer code form git simply run: +In order to refresh the code in a container and pull newer code from git run: ``` sudo docker exec -t -i /usr/bin/pull ``` + +### Using environment variables + +To set the variables pass them in as environment variables on the docker command line. + +Example: +``` +sudo docker run -d -e 'YOUR_VAR=VALUE' richarvey/nginx-php-fpm +``` + ## Logging and Errors + ### Logging All logs should now print out in stdout/stderr and are available via the docker logs command: ``` docker logs ``` +### WebRoot +You can set your webroot in the container to anything you want using the ```WEBROOT``` variable e.g -e "WEBROOT=/var/www/html/public". By default code is checked out into /var/www/html/ so if your git repository does not have code in the root you'll need to use this variable.