laradock/DOCUMENTATION/content/getting-started/index.md

6.2 KiB

title type weight
Getting Started index 2

Requirements

Installation

Choose the setup the best suits your needs.

A) Setup for Single Project

(Follow these steps if you want a separate Docker environment for each project)

A.1) Already have a PHP project:

1 - Clone laradock on your project root directory:

git submodule add https://github.com/Laradock/laradock.git

Note: If you are not using Git yet for your project, you can use git clone instead of git submodule .

To keep track of your Laradock changes, between your projects and also keep Laradock updated check these docs

Your folder structure should look like this:

+ project-a
  + laradock-a
+ project-b
  + laradock-b

(It's important to rename the laradock folders to unique name in each project, if you want to run laradock per project).

Now jump to the Usage section.

A.2) Don't have a PHP project yet:

1 - Clone this repository anywhere on your machine:

git clone https://github.com/laradock/laradock.git

Your folder structure should look like this:

+ laradock
+ project-z

2 - Edit your web server sites configuration.

We'll need to do step 1 of the Usage section now to make this happen.

cp env-example .env

At the top, change the APPLICATION variable to your project path.

APPLICATION=../project-z/

Make sure to replace project-z with your project folder name.

Now jump to the Usage section.

B) Setup for Multiple Projects:

(Follow these steps if you want a single Docker environment for all your project)

1 - Clone this repository anywhere on your machine (similar to Steps A.2. from above):

git clone https://github.com/laradock/laradock.git

Your folder structure should look like this:

+ laradock
+ project-1
+ project-2

2 - Go to nginx/sites and create config files to point to different project directory when visiting different domains.

Laradock by default includes app.conf.example, laravel.conf.example and symfony.conf.example as working samples.

3 - change the default names *.conf:

You can rename the config files, project folders and domains as you like, just make sure the root in the config files, is pointing to the correct project folder name.

4 - Add the domains to the hosts files.

127.0.0.1  project-1.test
127.0.0.1  project-2.test
...

If you use Chrome 63 or above for development, don't use .dev. Why?. Instead use .localhost, .invalid, .test, or .example.

Now jump to the Usage section.

Usage

Read Before starting:

If you are using Docker Toolbox (VM), do one of the following:


We recommend using a Docker version which is newer than 1.13.


Warning: If you used an older version of Laradock it's highly recommended to rebuild the containers you need to use see how you rebuild a container in order to prevent as much errors as possible.


1 - Enter the laradock folder and copy env-example to .env

cp env-example .env

You can edit the .env file to choose which software's you want to be installed in your environment. You can always refer to the docker-compose.yml file to see how those variables are been used.

Depending on the host's operating system you may need to change the value given to COMPOSE_FILE. When you are running Laradock on Mac OS the correct file separator to use is :. When running Laradock from a Windows environment multiple files must be separated with ;.

2 - Build the enviroment and run it using docker-compose

In this example we'll see how to run NGINX (web server) and MySQL (database engine) to host a PHP Web Scripts:

docker-compose up -d nginx mysql

Note: The web servers nginx, apache.. all depend on php-fpm, means if you just run, them they will automatically run the php-fpm for you, so no need to specify them in the up command. If you don't see them running then you may need run them as follow: docker-compose up -d nginx php-fpm mysql....

You can select your own combination of containers from this list.

(Please note that sometimes we forget to update the docs, so check the docker-compose.yml file to see an updated list of all available containers).


3 - Enter the Workspace container, to execute commands like (Artisan, Composer, PHPUnit, Gulp, ...)
docker-compose exec workspace bash

Alternatively, for Windows PowerShell users: execute the following command to enter any running container:

docker exec -it {workspace-container-id} bash

Note: You can add --user=laradock to have files created as your host's user. Example:

docker-compose exec --user=laradock workspace bash

You can change the PUID (User id) and PGID (group id) variables from the .env file)


4 - Update your project configurations to use the database host

Open your PHP project's .env file or whichever configuration file you are reading from, and set the database host DB_HOST to mysql:

DB_HOST=mysql

If you want to install Laravel as PHP project, see How to Install Laravel in a Docker Container.


5 - Open your browser and visit your localhost address `http://localhost/`. If you followed the multiple projects setup, you can visit `http://project-1.test/` and `http://project-2.test/`.