update installation docs

taylorotwell · taylorotwell · commit 8cf73188a5f4 · 2023-11-13T14:11:53.000-06:00
diff --git a/installation.md b/installation.md
@@ -2,16 +2,16 @@
 
 - [Meet Laravel](#meet-laravel)
     - [Why Laravel?](#why-laravel)
-- [Your First Laravel Project](#your-first-laravel-project)
-- [Laravel & Docker](#laravel-and-docker)
-    - [Getting Started On macOS](#getting-started-on-macos)
-    - [Getting Started On Windows](#getting-started-on-windows)
-    - [Getting Started On Linux](#getting-started-on-linux)
-    - [Choosing Your Sail Services](#choosing-your-sail-services)
+- [Creating A Laravel Project](#creating-a-laravel-project)
 - [Initial Configuration](#initial-configuration)
     - [Environment Based Configuration](#environment-based-configuration)
     - [Databases & Migrations](#databases-and-migrations)
     - [Directory Configuration](#directory-configuration)
+- [Docker Installation Using Sail](#docker-installation-using-sail)
+    - [Sail On macOS](#sail-on-macos)
+    - [Sail On Windows](#sail-on-windows)
+    - [Sail On Linux](#sail-on-linux)
+    - [Choosing Your Sail Services](#choosing-your-sail-services)
 - [IDE Support](#ide-support)
 - [Next Steps](#next-steps)
     - [Laravel The Full Stack Framework](#laravel-the-fullstack-framework)
@@ -50,52 +50,94 @@ Need extreme scaling? Platforms like [Laravel Vapor](https://vapor.laravel.com)
 
 Laravel combines the best packages in the PHP ecosystem to offer the most robust and developer friendly framework available. In addition, thousands of talented developers from around the world have [contributed to the framework](https://github.com/laravel/framework). Who knows, maybe you'll even become a Laravel contributor.
 
-<a name="your-first-laravel-project"></a>
-## Your First Laravel Project
+<a name="creating-a-laravel-project"></a>
+## Creating A Laravel Project
 
-Before creating your first Laravel project, you should ensure that your local machine has PHP and [Composer](https://getcomposer.org) installed. If you are developing on macOS, PHP and Composer can be installed within minutes via [Laravel Herd](https://herd.laravel.com). In addition, we recommend [installing Node and NPM](https://nodejs.org).
+Before creating your first Laravel project, make sure that your local machine has PHP and [Composer](https://getcomposer.org) installed. If you are developing on macOS, PHP and Composer can be installed within minutes via [Laravel Herd](https://herd.laravel.com). In addition, we recommend [installing Node and NPM](https://nodejs.org).
 
-After you have installed PHP and Composer, you may create a new Laravel project via the Composer `create-project` command:
+After you have installed PHP and Composer, you may create a new Laravel project via Composer's `create-project` command:
 
 ```nothing
 composer create-project laravel/laravel example-app
 ```
 
-Or, you may create new Laravel projects by globally installing the Laravel installer via Composer. Or, if you installed PHP and Composer via [Laravel Herd](https://herd.laravel.com), the Laravel installer is already available to you:
-
-```nothing
-composer global require laravel/installer
-
-laravel new example-app
-```
-
-After the project has been created, start Laravel's local development server using the Laravel's Artisan CLI `serve` command:
+Once the project has been created, start Laravel's local development server using Laravel Artisan's `serve` command:
 
 ```nothing
 cd example-app
 
 php artisan serve
 ```
 
-Once you have started the Artisan development server, your application will be accessible in your web browser at `http://localhost:8000`. Next, you're ready to [start taking your next steps into the Laravel ecosystem](#next-steps). Of course, you may also want to [configure a database](#databases-and-migrations).
+Once you have started the Artisan development server, your application will be accessible in your web browser at [http://localhost:8000](http://localhost:8000). Next, you're ready to [start taking your next steps into the Laravel ecosystem](#next-steps). Of course, you may also want to [configure a database](#databases-and-migrations).
 
 > **Note**  
 > If you would like a head start when developing your Laravel application, consider using one of our [starter kits](/docs/{{version}}/starter-kits). Laravel's starter kits provide backend and frontend authentication scaffolding for your new Laravel application.
 
-<a name="laravel-and-docker"></a>
-## Laravel & Docker
+<a name="initial-configuration"></a>
+## Initial Configuration
+
+All of the configuration files for the Laravel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
+
+Laravel needs almost no additional configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` file and its documentation. It contains several options such as `timezone` and `locale` that you may wish to change according to your application.
+
+<a name="environment-based-configuration"></a>
+### Environment Based Configuration
+
+Since many of Laravel's configuration option values may vary depending on whether your application is running on your local machine or on a production web server, many important configuration values are defined using the `.env` file that exists at the root of your application.
+
+Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.
+
+> **Note**
+> For more information about the `.env` file and environment based configuration, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration).
+
+<a name="databases-and-migrations"></a>
+### Databases & Migrations
+
+Now that you have created your Laravel application, you probably want to store some data in a database. By default, your application's `.env` configuration file specifies that Laravel will be interacting with a MySQL database and will access the database at `127.0.0.1`.
+
+> **Note**
+> If you are developing on macOS and need to install MySQL, Postgres, or Redis locally, consider using [DBngin](https://dbngin.com/).
+
+If you do not want to install MySQL or Postgres on your local machine, you can always use a [SQLite](https://www.sqlite.org/index.html) database. SQLite is a small, fast, self-contained database engine. To get started, update your `.env` configuration file to use Laravel's `sqlite` database driver. You may remove the other database configuration options:
+
+```ini
+DB_CONNECTION=sqlite # [tl! add]
+DB_CONNECTION=mysql # [tl! remove]
+DB_HOST=127.0.0.1 # [tl! remove]
+DB_PORT=3306 # [tl! remove]
+DB_DATABASE=laravel # [tl! remove]
+DB_USERNAME=root # [tl! remove]
+DB_PASSWORD= # [tl! remove]
+```
+
+Once you have configured your SQLite database, you may run your application's [database migrations](/docs/{{version}}/migrations), which will create your application's database tables:
+
+```shell
+php artisan migrate
+```
+
+If an SQLite database does not exist for your application, Laravel will ask you if you would like the database to be created. Typically, the SQLite database file will be created at `database/database.sqlite`.
+
+<a name="directory-configuration"></a>
+### Directory Configuration
+
+Laravel should always be served out of the root of the "web directory" configured for your web server. You should not attempt to serve a Laravel application out of a subdirectory of the "web directory". Attempting to do so could expose sensitive files present within your application.
+
+<a name="docker-installation-using-sail"></a>
+## Docker Installation Using Sail
 
 We want it to be as easy as possible to get started with Laravel regardless of your preferred operating system. So, there are a variety of options for developing and running a Laravel project on your local machine. While you may wish to explore these options at a later time, Laravel provides [Sail](/docs/{{version}}/sail), a built-in solution for running your Laravel project using [Docker](https://www.docker.com).
 
 Docker is a tool for running applications and services in small, light-weight "containers" which do not interfere with your local machine's installed software or configuration. This means you don't have to worry about configuring or setting up complicated development tools such as web servers and databases on your local machine. To get started, you only need to install [Docker Desktop](https://www.docker.com/products/docker-desktop).
 
 Laravel Sail is a light-weight command-line interface for interacting with Laravel's default Docker configuration. Sail provides a great starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.
 
-> **Note**  
+> **Note**
 > Already a Docker expert? Don't worry! Everything about Sail can be customized using the `docker-compose.yml` file included with Laravel.
 
-<a name="getting-started-on-macos"></a>
-### Getting Started On macOS
+<a name="sail-on-macos"></a>
+### Sail On macOS
 
 If you're developing on a Mac and [Docker Desktop](https://www.docker.com/products/docker-desktop) is already installed, you can use a simple terminal command to create a new Laravel project. For example, to create a new Laravel application in a directory named "example-app", you may run the following command in your terminal:
 
@@ -117,15 +159,15 @@ cd example-app
 
 Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
 
-> **Note**  
+> **Note**
 > To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
 
-<a name="getting-started-on-windows"></a>
-### Getting Started On Windows
+<a name="sail-on-windows"></a>
+### Sail On Windows
 
 Before we create a new Laravel application on your Windows machine, make sure to install [Docker Desktop](https://www.docker.com/products/docker-desktop). Next, you should ensure that Windows Subsystem for Linux 2 (WSL2) is installed and enabled. WSL allows you to run Linux binary executables natively on Windows 10. Information on how to install and enable WSL2 can be found within Microsoft's [developer environment documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
 
-> **Note**  
+> **Note**
 > After installing and enabling WSL2, you should ensure that Docker Desktop is [configured to use the WSL2 backend](https://docs.docker.com/docker-for-windows/wsl/).
 
 Next, you are ready to create your first Laravel project. Launch [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab) and begin a new terminal session for your WSL2 Linux operating system. Next, you can use a simple terminal command to create a new Laravel project. For example, to create a new Laravel application in a directory named "example-app", you may run the following command in your terminal:
@@ -148,7 +190,7 @@ cd example-app
 
 Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
 
-> **Note**  
+> **Note**
 > To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
 
 #### Developing Within WSL2
@@ -157,8 +199,8 @@ Of course, you will need to be able to modify the Laravel application files that
 
 Once these tools are installed, you may open any Laravel project by executing the `code .` command from your application's root directory using Windows Terminal.
 
-<a name="getting-started-on-linux"></a>
-### Getting Started On Linux
+<a name="sail-on-linux"></a>
+### Sail On Linux
 
 If you're developing on Linux and [Docker Compose](https://docs.docker.com/compose/install/) is already installed, you can use a simple terminal command to create a new Laravel project.
 
@@ -188,7 +230,7 @@ cd example-app
 
 Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
 
-> **Note**  
+> **Note**
 > To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
 
 <a name="choosing-your-sail-services"></a>
@@ -208,53 +250,6 @@ You may instruct Sail to install a default [Devcontainer](/docs/{{version}}/sail
 curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash
 ```
 
-<a name="initial-configuration"></a>
-## Initial Configuration
-
-All of the configuration files for the Laravel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
-
-Laravel needs almost no additional configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` file and its documentation. It contains several options such as `timezone` and `locale` that you may wish to change according to your application.
-
-<a name="environment-based-configuration"></a>
-### Environment Based Configuration
-
-Since many of Laravel's configuration option values may vary depending on whether your application is running on your local machine or on a production web server, many important configuration values are defined using the `.env` file that exists at the root of your application.
-
-Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.
-
-> **Note**  
-> For more information about the `.env` file and environment based configuration, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration).
-
-<a name="databases-and-migrations"></a>
-### Databases & Migrations
-
-Now that you have created your Laravel application, you probably want to store some data in a database. By default, your application's `.env` configuration file specifies that Laravel will be interacting with a MySQL database and will access the database at `127.0.0.1`. If you are developing on macOS and need to install MySQL, Postgres, or Redis locally, you may find it convenient to utilize [DBngin](https://dbngin.com/).
-
-If you do not want to install MySQL or Postgres on your local machine, you can always use a [SQLite](https://www.sqlite.org/index.html) database. SQLite is a small, fast, self-contained database engine. To get started, update your `.env` configuration file to use Laravel's `sqlite` database driver. You may remove the other database configuration options:
-
-```ini
-DB_CONNECTION=sqlite # [tl! add]
-DB_CONNECTION=mysql # [tl! remove]
-DB_HOST=127.0.0.1 # [tl! remove]
-DB_PORT=3306 # [tl! remove]
-DB_DATABASE=laravel # [tl! remove]
-DB_USERNAME=root # [tl! remove]
-DB_PASSWORD= # [tl! remove]
-```
-
-Once you have configured your SQLite database, you may run your application's [database migrations](/docs/{{version}}/migrations), which will create your application's database tables:
-
-```shell
-php artisan migrate
-```
-
-If an SQLite database does not exist for your application, Laravel will ask you if you would like the database to be created. Typically, the SQLite database file will be created at `database/database.sqlite`.
-
-<a name="directory-configuration"></a>
-### Directory Configuration
-
-Laravel should always be served out of the root of the "web directory" configured for your web server. You should not attempt to serve a Laravel application out of a subdirectory of the "web directory". Attempting to do so could expose sensitive files present within your application.
-
 <a name="ide-support"></a>
 ## IDE Support
 
