random72istaken / tall-stack

This is a TALL stack (Laravel) development environment (Docker) that I'd use to instantly start a new web application.

بسم الله الرحمن الرحيم

TALL Stack DevContainer

This is a TALL stack (Laravel) development environment (Docker) that I'd use to instantly start a new web application.

Until the customization feature is ready, this preset is clearly opinionated.

~ Inspired by the actual tall preset!

Stack

Containers

1. PHP:8.1.9 (Port: 80)
   • Xdebug:3.1.5 (Port: 9003)
2. MySQL:8.0.30 (Port: 3306)
3. Redis:alpine (Port: 6379)
4. Mailhog:latest (Port: 1025 | 8025)
5. MinIO:latest (Port: 9000 | 8900)
6. Soketi:latest-16-alpine (Port: 6001 | 9601)
7. Expose:latest (Port: 8080 | 4040)

Packages

• Laravel Sail v1.15.4 (DevContainer)
• TailwindCSS v3.1.8 (Forms and Typography Plugins Installed)
• Alpine.js v3.10.3 (Focus Plugin Installed)
• Livewire v2.10.7
• Laravel v9.26.1
• Vite.js v2.9.14
  • Laravel Plugin v0.2.4
  • Livewire Plugin v0.1.15
• TALL Stack Builder v1.0.0

Opinionated (To Be Optional)

• Pest v1.21.3 (Testing Framework)
• Laravel Echo v1.13.1 (Soketi)
  • Pusher PHP Server v7.4.0 (Soketi)
• Laravel Telescope v4.9.2 (Local Only)
• Laravel Scout v9.4.10 (Database Driver)
• Media-Library v10.4.4
• Filament v2.15.28 (Admin, Forms, Tables, and Notifications)
  • Including Spatie's Media-Library Plugin
• Good Loader v1.1.1
• Good Night v1.0.0

Modifications

Here are some core changes to the application structure:

• Environment Related

  • When the container runs, Expose will share the application automatically; but it's still protected with HTTP authentication using the credentials set in the environment variables.

    • The site's generated domain can be found in Expose's dashboard yet at port 8080, or can be expected from Docker's -expose- container's log.

  • Set a lot of essential and supportive VSC extensions to be installed along the environment.

    Note PHP Intelephense has a quick command to Index workspace for some PHP intellisense.

  • Overridden essential settings for VSC and its extensions.

    • You should check them out. Especially the HTML attribute wrapping strategy, wrapAttribute, used by Blade Formatter extension.

  • Enforced a bit of essential VSC keybindings too.

  • Included the following in version-control:

    • Laravel Sail package in order for this whole thing to work with only Docker installed.

    • Xdebug dev-container VSC settings to start debugging easily.

    • Vite's built-assets directory [/public/build].

  • Excluded some unrelated paths from version-control, such as Homestead.json, for instance.

  • Configured Vite.js to hot-reload the page upon file changes while preserving the state of Livewire components...

    Note If the change was done on the page itself though, which happens to contain an inlined Livewire component, then the state will be reset too in that case.

    Warning Please be aware that Vite's traffic is blocked by Brave browser's Shield feature. So make sure you click on it and disable it for localhost.

  • Uncommented and therefore exposed Laravel Echo for real-time broadcasting; as Soketi is already setup with Pusher's boilerplate.

• Package Configuration

  • MinIO is integrated to be the default Filesystem Disk. (s3)

  • Livewire's temporary upload filesystem is set to local though.

    Warning Remember to set your PHP's "max file upload size" and "max execution time" in production before uploading anything!

  • Livewire's default layout was set to the custom master layout we've created.

  • Pest is setup to ignore Vite HMR exception while testing, and to consider [tests/Unit] directory.

  • Some styles are defined in tailwind.config.js file, including:

    • Defined content for Blade file directories.

    • Added Filament colors: [primary, success, warning and danger].

    • Set the dark-mode to be class, and added a dark-primary colors.

      • (Click Laravel's logo in the home page! 😉)

    • Specified font-mulish as a font-family class.

  • Set visibility to public in Media-Libary's config file, and set the storage to s3.

  • Built Filament's theme to honor Tailwind's colors, and used it in a dedicated service provider.

  • Modified Filament's configurations as follows:

    • Enabled dark mode.

    • Hidden the 2 widgets from the default dashboard, and the default logo.

    • Linked to the default favicon.ico we've got for the app.

    • Set the default notification alignment to bottom/right.

• Project Structure

  • Moved lang folder into resources.

  • A Prettier's configuration file is initialized in the project's root directory.

  • Added and registered a Services/Helpers/general.php helper file.

  • Added Laravel's logo as a cute favicon.

  • Designed a master layout component, with @stack()s for various elements.

    • Applied @goodLoader directive to fade the view in.

  • Redesigned a home view to shout out for the TALL stack!

    • Replacing the default route with one for home, of course.

    • Pointing RouteServiceProvider's HOME constant to /.

    • Added Mulish font link from Google Fonts.

  • Aborted /login requests with 404.

  • Organized the original environment variables and package-specific ones.

• Extra Modifications

  • Added a environment user to be generated by default.

    • Allowed this user to access Filament in production.

  • Added an environment variable, PASSWORD_TIMEOUT, which points to the setting in config/auth.php file.

Customization

Soon, (in sha' Allah)...

Execution

First you'd need Docker set up; recommendedly hooked to an Ubuntu OS. If you're on Windows - for any weird reason, you can use WSL2 to spin up Ubuntu inside it.

Construction

Most of the following process is done with VSC; not PhpStorm. 😋

0. Get the template files using either of the two ways:

   • Use this package as a template and clone it locally.

   • Download the last release or master's source-code, open VSC, toggle its terminal into a bash session (Ubuntu's), then run following:

     cd ~/Code
     unzip ~/Downloads/tall-stack-x.x.x.zip -d ./
     mv tall-stack-x.x.x tall-stack

     • Replacing tall-stack with your project name; kebab-cased!

     • Assuming that there's a Code directory inside the ~ (home) directory, where projects are usually constructed.

     • Pretending that the downloaded source-code is in ~/Downloads directory.

1. Duplicate the environment variables file and launch VSC in the project's directory:

   cd tall-stack
   cp .env.example .env
   code -r .

2. Open .devcontainer/devcontainer.json and set the name to your project name.

   • Go through the VSC extensions list and comment out what you don't like.

   • Consider supporting PHP Intelephense extension by purchasing their license.

3. Open the .env file and name your application in the following variables:

   APP_NAME="TALL Stack" # "Application Name"
   ENV_USER_NAME=Sail
   ENV_USER_EMAIL[email protected]
   ENV_USER_PASSWORD=password
   DB_DATABASE=tall_stack # application_name
   EXPOSE_AUTH_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Register At https://expose.dev
   EXPOSE_USERNAME=sail # HTTP Authentication
   EXPOSE_PASSWORD=password # HTTP Authentication

4. Install the Remote Development extension.

5. Run Remote-Containers: Reopen in Container from the command palette.

6. Toggle the terminal into a bash session (within the new container) and run the following commands:

   composer install
   php artisan tall-stack:build

   Note
   The command will also ensure all the preset package's boilerplate are removed. And that the project now has Laravel's default structure; almost.

7. Navigate to MinIO's dashboard with: localhost:8900

   • Sign in using sail and password.
   • Create a bucket named: local.
   • Set its Access Policy to public.

8. Restart the container by running Remote-Containers: Rebuild Container from the command palette.

9. Compile your front-end assets with Vite via NPM:

   npm run dev

   Warning: You must ensure that Vite is running throughout development; an exception will be thrown for loading without it!

   • Remember that, when you're tired of it, you can disable the VSC notification - that appreas after running this command - from the cog in its corner!

Now you can visit http://localhost and build something tall! 🙂

• If you close the running VSC window, it will gracefully close down the container with it; after 10 seconds.

• If you run the exact VSC window again, or if you open the project folder and Remote-Containers: Reopen in Container, the container will run with ease.

• If you want to debug the application, just make sure you've got the Xdebug browser extension installed, head to the Run and Debug view, hit F5 to start listening, put a break point in some PHP file, activate the extension in the browser and head to localhost.

  • If you're on Windows, there is an additional step shown in; follow the Linux Host IP Configuration section in the docs.

Destruction

If you're done with the project and wish to delete it completely, do the following:

1. Delete the project containers:

   docker rm $(docker ps -a -q --filter name=tall-stack_)

   • Where tall-stack is the project name.

2. Use Docker Desktop to check for leftover images and volumes. (Both can be inspected)

3. Delete the main project's folder with privileges:

   sudo rm -rf ~/Code/tall-stack

Warning
Missing one of these steps could easily ruin the building process of the development environment container, and resulting weird anomalies all around. Especially the folder in step 3.

Development

Pull-requests are extremely welcome... 😗👍🏻

TODO

• Abstract away all the opinionated setup...
  • Create a separate package for easier installation.
    • (The details are over here)
  • Rework documentation.
• Integrate Cypress as a front-end testing framework.
• Write Pest and Cypress tests, one day!
• Create a wiki page for VSC extensions and shortcuts.
• Create a wiki page for Laravel modules and working with sub-domains.

Notes

• When updating packages, and when you're inside the running container, remove the vendor/bin/sail binary and then start updating.

  • If updating fails, and you got out of the container, you'd need to manually recover that file in order for the container to run again.

    cp ~/Code/tall-stack/vendor/laravel/sail/bin/sail ~/Code/tall-stack/vendor/bin/

Credits

• The awesome framework creators.
• The original TALL Stack preset and their home design.
• TailwindCSS Snippets repository.
• RhysLees for the "interactive prompts" tip.
• rennokki for Soketi and oanhnn for its integration.

If you like the preset, please do 🌟 every repository linked around here; except this preset.

DO NOT STAR THIS PRESET! 😍

والحمد لله رب العالمين