From 9135e8aa1fa07f5a682c7bf83be314859b25c0c4 Mon Sep 17 00:00:00 2001 From: Mahmoud Zalt Date: Wed, 17 Feb 2016 17:55:40 +0200 Subject: [PATCH] upgrade the read me --- README.md | 201 +++++++++++++++++++----------------------------------- 1 file changed, 71 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index 0d3ee97b..3312d068 100644 --- a/README.md +++ b/README.md @@ -3,169 +3,120 @@ [![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](http://www.zalt.me) -### What is this? -**LaraDock** is a starter project to get you up and running with **Laravel** 5 and **Docker**. +## Contents -It includes a Laravel `v5.1.10` fresh installation and a pre-configured **Docker Compose** file (containg most required **images** to run a Laravel application). -**Watch the demonstration video [https://www.youtube.com/watch?v=3YQsHe6oF80](https://www.youtube.com/watch?v=3YQsHe6oF80).** +- [Intro](#Intro) +- [Requirements](#Requirements) +- [Usage](#Usage) +- [Documentation](#Documentation) +- [Supported Images](#Supports) ![](http://s11.postimg.org/uqpl3efab/laradock.jpg) + + +### What is LaraDock? + +**LaraDock** helps you run your **Laravel** App on **Docker** in seconds. + +LaraDock strives to make the development experience easier. +It contains pre-packaged Docker Images that provides you a wonderful development environment without requiring you to install PHP, NGINX, MySQL, REDIS, and any other software on your local machine. + + ### What is Docker? [Docker](https://www.docker.com) is an open-source project that automates the deployment of applications inside software containers, by providing an additional layer of abstraction and automation of [operating-system-level virtualization](https://en.wikipedia.org/wiki/Operating-system-level_virtualization) on Linux, Mac OS and Windows. ### What is Laravel? -Are you serious!! +Seriously!!! -### Why Docker not Vagrant?! +### Why Docker not Vagrant!? [Vagrant](https://www.vagrantup.com) gives you Virtual Machines in minutes while Docker gives you Linux Containers in seconds. Instead of providing a full Virtual Machines, like you get with Vagrant, Docker provides you **lightweight** Virtual Containers, that share the same kernel and allow to safely execute independent processes. -### What's next? - -LaraDock strives to make the development experience easier. -And it is inspired by [Laravel Homestead](http://laravel.com/docs/master/homestead). - -*In the near future LaraDock will become a stand-alone package that manages your Docker Virtual Containers as Homestead does with your Vagrant Virtual Machines.* - - - - ### Questions? -If you have any questions please share it with us on [![Join the chat at https://gitter.im/LaraDock/laradock](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/LaraDock/laradock?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) or email me on (mahmoud@zalt.me). +[![Join the chat at https://gitter.im/LaraDock/laradock](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/LaraDock/laradock?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -## Highlights - -__Included Images:__ - -- [NGINX+PHP](https://hub.docker.com/r/laradock/phpnginx/) -- [MySQL](https://hub.docker.com/r/laradock/mysql/) -- [Redis](https://hub.docker.com/r/laradock/redis/) -- [Beanstalked](https://hub.docker.com/r/laradock/beanstalkd/) -- [Data Volume](https://hub.docker.com/r/laradock/data/) (for MySQL & Redis) - -*Note: PHP and NGINX are in one container, I will split them whenever I see the need for it.* - - - -## Contents - -- [Requirements](#Requirements) -- [Tutorial](#Tutorial) -- [Usage](#Usage) -- [Documentation](#Documentation) - ## Requirements -- Docker toolbox ([Download](https://www.docker.com/toolbox)) this includes: - - VirtualBox - - Docker Client - - Docker Machine - - Docker Compose (Required, minimum version 1.4.0) - - Docker Kitematic (Not Important) +- Laravel Installation +- Docker Toolbox ([Download](https://www.docker.com/toolbox)) - Git ([Download](https://git-scm.com/downloads)) - Composer ([Download](https://getcomposer.org/download/)) *Note: Git & Composer can be installed on Docker Containers if you don't want to install them on your machine. (But you have to do this yourself for now).* - -## Tutorial - -What's better than a quick [video](https://www.youtube.com/watch?v=3YQsHe6oF80) ;) ## Usage -1 - First clone the project +1 - First install any version of Laravel, or use any of your existing Laravel projects. + +2 - Open your terminal and go to your Laravel project directory. + +3 - Create a new folder on the root directory of your Laravel project and name it `docker` then go into it. ```bash - git clone https://github.com/LaraDock/laradock laradock +mkdir docker && cd $_ ``` -2 - Inside `laradock` there are 2 directories (Laravel and Docker) let's start with Laravel +3 - Clone the LaraDock repository inside that `docker` folder. ```bash - cd laradock/laravel +git clone https://github.com/LaraDock/laradock.git . ``` -3 - Install the Composer packages +4 - Find your Docker IP address. + +- If you are on Linux OS: your IP Address is `127.0.0.1` because the containers run directly on your localhost. +- If you are on MAC or Windows OS and using the **docker-machine**: start your docker machine then type `docker-machine ip {VM-Name}` to get your IP Address. *(Default is 192.168.99.100)* +- If you are on MAC or Windows OS and using **boot2docker**: type `boot2docker ip` when boot2docker is up, to get your IP Address. + +5 - Open your hosts file `/etc/hosts`. ```bash - composer install +sudo nano /etc/hosts ``` -4 - On laravel's root directory `laradock/laravel`, rename the file `.env.docker` to `.env` +6 - Map your `Docker IP` to the `laravel.dev` domain, by adding the following to the `hosts` file. ```bash - sudo mv .env.docker .env +xxx.xxx.xxx.xxx laravel.dev ``` -5 - Provide some permissions (directories should be writable by the web server) +Don't forget to replace the `xxx.xxx.xxx.xxx` with your Docker IP Address. + +7 - Open `docker-compose.yml` file and replace the `xxx.xxx.xxx.xxx` with your Docker IP Adress as well. + +8 - Open your Laravel's `.env` file and set the `DB_HOST` and the `REDIS_HOST` to `laravel.dev` instead of the default `127.0.0.1`. + +```env +DB_HOST=laravel.dev +REDIS_HOST=laravel.dev +``` + +9 - Finally run the containers to start coding. ```bash - sudo chmod -R 777 storage && sudo chmod -R 777 bootstrap/cache +docker-compose up -d ``` -6 - Now let's start with the Docker stuff - -```bash - cd ../docker -``` - -7 - Edit the hosts file `/etc/hosts` on your machine, to map your `Docker IP` to the `laravel.dev` domain - -```bash - sudo nano /etc/hosts -``` - -`127.0.0.x laravel.dev` - - -> To find the IP address: -> -> - if you are on Linux, the containers run directly on your localhost so this `127.0.0.1` will be your IP Address. -> - if you are on MAC and using **boot2docker**, type `boot2docker ip` when boot2docker is up. -> - if you are on MAC and using **docker-machine**, type `docker-machine ip {VM-Name}` after starting a virtual machine. -> - if you are on Windows, check the Docker documentation for how you get the VM IP Address. - -8 - Additional step for `Docker-Machine` users only. *(Skip this if you are not using `Docker-Machine`)*: - -a. Edit this file `docker/docker-compose.yml` - -b. Uncomment: - -```yaml - # extra_hosts: - # - "laravel.dev:xxx.xxx.xxx.xxx" -``` -c. Replace `xxx.xxx.xxx.xxx` with your the VM IP address. - - -9 - Finally run the containers and start coding. - -*"Note: Only the first you run this command will take up to 7 minutes (depend on your connection speed) to download the images to your local machine, Only once in life.* - -```bash - docker-compose up -d -``` +*"Note: Only the first time you run this command, it will take up to 7 minutes (depend on your connection speed) to download the images to your local machine, Only once in life.* 10 - Open your browser and visit `http://laravel.dev` -You should see a page like this: -![](http://s29.postimg.org/8cvh7wq2f/Screen_Shot_2015_08_21_at_9_23_19_PM.png) - +> Debugging: if you faced an error, it might be that you forget to provide some permissions for Laravel, so try running the following command on the Laravel rood directory: +`sudo chmod -R 777 storage && sudo chmod -R 777 bootstrap/cache` @@ -200,23 +151,9 @@ docker-compose rm -f -#### Delete an Image (remove the unused software) -To delete an image (software), just edit the `laradock/docker/docker-compose.yml` file. +#### Remove Container +To prevent a container (software) from running, open the `docker-compose.yml` file, and comment out the container section or remove it entirely. -**Example:** Assume you want to remove the `Beanstalkd` Container. - - -Open the `docker-compose.yml` file, and comment out the `beanstalkd` section: - -```yml -# Beanstalkd Container #----------------------------------- -# beanstalkd: -# image: laradock/beanstalkd:latest -# container_name: beanstalkd -# ports: -# - "11300:11300" -# privileged: true -``` #### Add an Image (add a software to run with other Containers) To add an image (software), just edit the `laradock/docker/docker-compose.yml` and add your container details, to do so you need to be familiar with the [docker compose file syntax](https://docs.docker.com/compose/yml/). @@ -244,7 +181,20 @@ All the images are open source and hosted on the [Docker Hub](https://hub.docker *If you find any bug or you have and suggestion that can improve the performance of any image, please consider contributing. Thanks in advance.* #### View the Log files -The Log files are stored in the `laradock/docker/logs` directory. +The Log files are stored in the `docker/logs` directory. + + + + +## Highlights + +__Currently Supported Docker Images:__ + +- [NGINX+PHP](https://hub.docker.com/r/laradock/phpnginx/) +- [MySQL](https://hub.docker.com/r/laradock/mysql/) +- [Redis](https://hub.docker.com/r/laradock/redis/) +- [Beanstalked](https://hub.docker.com/r/laradock/beanstalkd/) +- [Data Volume](https://hub.docker.com/r/laradock/data/) (for MySQL & Redis) @@ -261,8 +211,6 @@ All contributions are welcomed. - - ## Credits [![Mahmoud Zalt](https://img.shields.io/badge/Author-Mahmoud%20Zalt-orange.svg)](http://www.zalt.me) @@ -272,10 +220,3 @@ All contributions are welcomed. ## License [MIT License (MIT)](https://github.com/laradock/laradock/blob/master/LICENSE) - - - - - - -