This repository contains modular Deployer scripts for provisioning servers and deploying Laravel applications. It includes configurations for Nginx, PHP-FPM, Supervisor, Node.js + Puppeteer, Redis, and a self-hosted Garage S3 storage cluster.
The best way to use these scripts is to add this repository as a git submodule to your Laravel project. Run the following command from the root of your project:
git submodule add git@github.com:slimani-dev/.deployer.git .deployerNext, copy the deploy.php.example file to the root of your Laravel project:
cp .deployer/deploy.php.example deploy.phpFinally, open deploy.php in your editor and update the configuration block with your repository, domain, server IP, and secrets.
You MUST add the following to your root project's .gitignore file to avoid leaking credentials:
/.deployer
deploy.phpNote: The garage/secrets.json file auto-generated by this module is already ignored by this module's local .gitignore, but it's best to secure the whole folder out of your main codebase.
To provision a brand new server, you only need exactly two things:
- Root user access to the target destination.
- SSH keys properly configured for the root user.
You will also need Deployer installed on your local machine.
Global Installation (Recommended):
composer global require deployer/deployerYou can then run commands simply using dep provision.
Local Installation:
composer require deployer/deployer --devIf installed locally, you must prefix commands with your vendor binary: vendor/bin/dep provision.
The entire infrastructure setup and code rollout is handled in just two commands. Run these from your local machine.
dep provisionThis command installs all required packages (PHP, Node, Nginx, Redis, Supervisor, Garage, Chrome/Puppeteer), sets up the deployer user, and applies permissions.
At the very end of this process, the script will output a public SSH key, which looks similar to this:
================= GIT DEPLOY KEY =================
Copy the following key and add it to your Git repository (GitHub/GitLab) Deploy Keys:
ssh-ed25519 AAAAC3NzaC1lZT....... root@YourServer
==================================================
CRITICAL: You must copy this public key and add it to your project's repository settings as a Deploy Key (or to your personal Git account) before running dep deploy, otherwise the server will be rejected when trying to clone your code!
dep deployThis command pulls the code, installs PHP and JS vendors, maps .env variables, and restarts the backend services.
Because the .env file is generated from your .env.example, make sure your .env.example is fully filled out with the structural defaults your application expects!
Crucial Environment Settings:
Before your app goes live, verify the copied .env file has these fundamental production values:
APP_ENV=productionAPP_DEBUG=falseAPP_URL=https://your-domain.com
After your very first deploy finishes, you should manually generate the application key and cache:
dep artisan:key:generate
dep artisan:config:cacheYou only need to do this once on the initial setup because the APP_KEY is not generated by default.
During the provisioning and deployment processes, the deployer scripts will automatically inject and update several variables in your project's .env file (located at shared/.env on the server).
Make sure these keys exist with empty or default values in your local .env.example so the scripts can safely find and replace them!
These are populated using the target host configuration in deploy.php:
DB_DATABASEDB_USERNAMEDB_PASSWORD
These are generated dynamically via Garage on the server, assigning an isolated bucket and dedicated user keys for your application:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_DEFAULT_REGION(Always set togarage)AWS_BUCKETAWS_USE_PATH_STYLE_ENDPOINT(Always set totrue)AWS_URLAWS_ENDPOINT
This specifies the path to the downloaded Chrome binary which Puppeteer or Spatie Browsershot can use to generate PDFs and screenshots:
CHROME_PATH(Typically/usr/bin/puppeteer-chrome)