Sail Separate integration docs added (#210)

* Sail Separate integration docs added

* old Laravel sail references hyperlinked to new page

* removed irrelevant default configuration

* custom credentials doc elaboration

* docs updated

* wip

* fixed issues in `sail.blade.md`

* used `>` in `configuration.blade.md`

* fixed typo for `:`

* Update source/docs/v3/quickstart.blade.md

* Update source/docs/v3/configuration.blade.md

* removed irrelevant pieces

* removed h2, added h1

* Update source/docs/v3/integrations/sail.blade.md

Co-authored-by: lukinovec <lukinovec@gmail.com>

* removal rollback

* Update the Sail integration guide

* Add guide for privilege granting automation

* trigger ci

---------

Co-authored-by: Chinmay Purav <experiment@webscientist.xyz>
Co-authored-by: Samuel Štancl <samuel@archte.ch>
Co-authored-by: lukinovec <lukinovec@gmail.com>

navigation.php

@@ -208,6 +208,7 @@ return [
                         'Livewire' => 'integrations/livewire',
                         'Orchid' => 'integrations/orchid',
                         'Sanctum' => 'integrations/sanctum',
+                        'Sail' => 'integrations/sail',
                         'Vite' => 'features/vite-bundler',
                     ],
                 ],

source/docs/v3/configuration.blade.md

@@ -60,10 +60,8 @@ The list of domains that host your [central app]({{ $page->link('the-two-applica
 This config array lets you enable, disable or add your own [tenancy bootstrappers]({{ $page->link('tenancy-bootstrappers') }}).
 
 ### Database {#database}
-> Note: If you're using [Laravel Sail](https://laravel.com/docs/9.x/sail), ensure that `DB_USERNAME` has the necessary permissions. You can grant privileges to users by running `GRANT ALL PRIVILEGES on *.* to 'sail'@'%';` in the MySQL console. 
-> Once you have finalized the permissions, always be sure to reload all the privileges `FLUSH PRIVILEGES;` 
 
-`tenancy.database.*`
+> If you're using Laravel Sail, please refer the [Laravel Sail integration guide]({{ $page->link('integrations/sail') }}).
 
 This section is relevant to the multi-database tenancy, specifically, to the `DatabaseTenancyBootstrapper` and logic that manages tenant databases.
 

source/docs/v3/integrating.blade.md

@@ -16,4 +16,5 @@ If you're using the [automatic mode]({{ $page->link('automatic-mode') }}) & [mul
 - [Laravel Telescope]({{ $page->link('integrations/telescope') }})
 - [Livewire]({{ $page->link('integrations/livewire') }})
 - [Laravel Sanctum]({{ $page->link('integrations/sanctum') }})
+- [Laravel Sail]({{ $page->link('integrations/sail') }})
 - [Vite]({{ $page->link('features/vite-bundler') }})

source/docs/v3/integrations/sail.blade.md

@@ -0,0 +1,28 @@
+---
+title: Laravel Sail integration
+extends: _layouts.documentation
+section: content
+---
+
+# Laravel Sail {#sail}
+
+> Note: This guide covers Sail integration using MySQL. The steps described in the guide will need adjustments if you're using a database other than MySQL.
+
+> The default Sail user's name is determined by the `DB_USERNAME` variable in your `.env`. For this guide, we'll be using the username `sail`.
+
+The default Sail user can only perform the create, read, update and delete operations in the central database. To allow the user to perform these operations in the tenant databases too, log in to Sail's MySQL shell as the root user (`docker-compose exec mysql bash`, then `mysql -u root -p` – by default, the password is determined by the `DB_PASSWORD` variable in your `.env`) and grant the Sail user access to all databases by running the following statements:
+
+```sh
+GRANT ALL PRIVILEGES on *.* to 'sail'@'%';
+FLUSH PRIVILEGES;
+```
+
+You have to grant the privileges every time you re-run a container. To automate granting the privileges, create an SQL file with the previously mentioned SQL statements to grant all privileges to the Sail user. Then, add the path to the SQL file to `docker-compose.yml`'s MySQL volumes:
+
+```yml
+mysql:
+    # ...
+    volumes:
+        # ...
+        - 'PATH_TO_THE_SQL_FILE:/docker-entrypoint-initdb.d/SQL_FILE_NAME.sql'
+```

source/docs/v3/quickstart.blade.md

@@ -82,7 +82,7 @@ In other words, it creates & migrates the tenant's database after he's created
 
 ## Central routes {#central-routes}
 
-We'll make a small change to the `app/Providers/RouteServiceProvider.php` file. Specifically, we'll make sure that central routes are registered on central domains only. 
+We'll make a small change to the `app/Providers/RouteServiceProvider.php` file. Specifically, we'll make sure that central routes are registered on central domains only.
 
 ```php
 protected function mapWebRoutes()
@@ -144,7 +144,6 @@ If you're using Laravel Sail, no changes are needed, default values are good to
     'localhost',
 ],
 ```
-
 ## Tenant routes {#tenant-routes}
 
 Your tenant routes will look like this by default:
@@ -177,8 +176,8 @@ Route::get('/', function () {
 To have users in tenant databases, let's move the `users` table migration (the file `database/migrations/2014_10_12_000000_create_users_table.php` or similar) to `database/migrations/tenant`. This will prevent the table from being created in the central database, and it will be instead created in the tenant database when a tenant is created — thanks to our event setup.
 
 ## Creating tenants {#creating-tenants}
-> Note: If you're using [Laravel Sail](https://laravel.com/docs/9.x/sail), ensure that `DB_USERNAME` has the necessary permissions. You can grant privileges to users by running `GRANT ALL PRIVILEGES on *.* to 'sail'@'%';` in the MySQL console.
-> Once you have finalized the permissions, always be sure to reload all the privileges `FLUSH PRIVILEGES;`
+
+> If you're using Laravel Sail, please refer the [Laravel Sail integration guide]({{ $page->link('integrations/sail') }}):
 
 For testing purposes, we'll create a tenant in `tinker` — no need to waste time creating controllers and views for now.