Starting a new Laravel Project

Starting a new Laravel Project

Starting a new Laravel Project

This step-by-step process should help you get a new Laravel instance installed and configured.

Once complete, you will have the Laravel framework installed with the project’s Docker container running. Through that, you will be able to access it in your web browser.

In this guide, you will:

  • Create a new directory for your Laravel project
  • Install a new instance of the Laravel framework
  • Add an alias for Laravel's Sail tool
  • Start Laravel's Docker container
  • Verify everything is working correctly

Prerequisites

Prior to completing this tutorial, you will need to ensure your system is ready with these things:

  • PHP Runtime
  • Composer Package Manager
  • Docker
  • Laravel Installer tool installed and available globally

For help with these things, please visit my Preparing your Environment tutorial.

If you are working from an environment I've not yet covered, contact me letting me know your situation, and I'll see if I can get some documentation added for you.


Create a Directory for your Code

With the Laravel Installer now available, you have a ready-made tool to create a new installation of Laravel.

Where do you want to use it? Where should all the code be stored on your computer?

Keeping in mind that you may end up with multiple projects, it's best to organize it into a common folder early.

I recommend creating a ‘code’ folder for this purpose.

On unix-based systems, such as linux and mac, ~ is used as a representation of the current user’s home directory, and can be used as shorthand. For example, in my case, typing ~ is the same as typing /home/james.

Create a simple 'code' directory and navigate into it.

cd ~
mkdir code
cd code

mkdir code

You now have a ‘code’ directory inside your home directory, and are ready to issue commands within it.


Install Laravel

As a starting example, let’s use the Laravel installer to create a new folder called learning_laravel, and install laravel inside it:

laravel new learning_laravel

learning_laravel could be anything you like, and should describe what you are building. The more descriptive of what you are building, the better. For the sake of simplicity, avoid spaces or special characters.

These tutorials will continuing assuming a folder named learning_laravel, You are free to change this to whatever you like at this time, but will need to modify subsequent commands to match your folder name.

The installer will create a lot of output as it installs the base code and numerous third-party packages used by the laravel system.

Once completed, you should see an Application ready! Build something amazing. line.

laravel new completed


Starting the Docker Container

Laravel comes with a tool called 'sail' which makes it simple to quickly get your new Laravel installation running in Docker.

Install sail:

php artisan sail:install

You'll be prompted to choose services to include. Unless you have a specific requirement, I recommended choosing mysql. Once completed, you should see a message stating Sail scaffolding installed successfully.

The sail tool lives within Composer's bin folder. Accessing it requires including the path vendor/bin/sail.

To make things easier, you should add an alias for this, as recommended by the makers of Laravel and Sail.

alias sail='bash vendor/bin/sail'

This alias informs your system that sail should be treated as shorthand for vendor/bin/sail.

However, executing this command will only add the alias for your current working session. To automatically add this alias for future sessions as well, you should add the command to your .bashrc file.

echo "alias sail='bash vendor/bin/sail'" >> ~/.bashrc

sail alias

To use sail, navigate into the new project directory and call a sail command to create and start the Docker container.

cd learning_laravel
sail up

This may take a while on first run, as Docker will be downloading numerous packages to create a full host of server environments for your laravel applications. Think of this as an opportunity to contemplate all the amazing things you will be building in the coming months.

It can be hard to know when it has completed processing. The easiest way to be certain everything has finished is to wait for one or more lines showing [APIv1] KEEPALIVE /api/v1/events for mailhog.

Once completed, If everything went as expected, your terminal window should be showing you realtime information about the docker environment.

sail

This is the first time you are testing your Docker installation. If you see a Docker is not running error at this point, please review Troubleshooting Docker.

You should now be able to visit http://localhost in your browser and see Laravel's default 'welcome' page.

localhost tells your browser to treat your local computer as a webserver. The browser should find Docker's webserver running and give you back the output of your new Laravel installation.


A Note on Starting Docker via sail

You will find that your terminal window is now giving you real-time information about the docker container. You can close this out and regain control of your terminal using control+c. This will, however, also stop the docker container.

While this can be very useful, it’s also possible to have the process detach from the terminal so that you can continue to use the terminal for other things. This is as simple as adding a ‘-d’ to the command.

vendor/bin/sail up -d

This is a good default way to start docker, with the non-detached option useful if you find yourself needing to troubleshoot something.

I recommend starting sail without the -d flag and opening a new terminal window for subsequent command line operations. You never know when information from Docker will be useful, and this way you always have it available.

sail detached

Conclusion

That’s it, you’ve got a clean, new, and up-to-date installation of Laravel running, and are ready to move on to the next tutorial, First Steps with Git.


Additional Resources

To learn about alternative Laravel installation approaches, see https://laravel.com/docs/master

To learn about Laravel Sail, visit https://laravel.com/docs/master/sail

For a high-level view of Docker, see https://medium.com/swlh/introduction-to-docker-96aad5eabb30