SST Laravel is an unofficial extension of SST created by Kirschbaum Development to deploy your Laravel application to AWS behind a robust, reliable and scalable infrastructure, with all the power of SST.
SST is a framework that makes it easy to build modern full-stack applications on your own infrastructure.
Behind the scenes, this extension uses the SST Cluster + Service component, which deploys custom Docker containers to AWS Fargate. It all gets deployed on your own AWS account, and you have full control over the infrastructure and which services are connected to your application.
This package deploys a full-blown infrastructure in AWS, with zero downtime deployments, as it can be seeing in the image below.
Behind the scenes, we use the powerful PHP containers from Serverside Up.
- NodeJS.
- Have AWS CLI installed and configured.
- Guide on how to set up IAM Credentials here.
Pull in the package using npm:
npm install @kirschbaum-development/sst-laravel --saveTo get started quickly, you can use the init command:
npx sst-laravel initTo start using, you only need to import the component in your sst.config.ts file:
import { LaravelService } from "@kirschbaum-development/sst-laravel";And now you can start using the Laravel SST component. All the configuration options are Typescript files with documentation, so
To check the full list of options. check here.
Below is an example of setting up your application to receive HTTP requests, on the laravel-sst-demo.example.com domain (with SSL), with auto-scaling with a max of 3 servers.
const app = new LaravelService('MyLaravelApp', {
web: {
cpu: 1024,
memory: 2048,
domain: {
dns: sst.cloudflare.dns(),
name: 'laravel-sst-demo.example.com',
},
scaling: {
min: 1,
max: 3,
}
},
});Check all the web options here.
Beyond HTTP requests, you can set up one or more workers for your Laravel application. Workers are meant to run background commands like Laravel Horizon, the Laravel Scheduler or any background command you may need to run.
SST Laravel will automatically deploy and configure worker containers running your configured commands. See some examples below.
Running the Laravel scheduler
const app = new LaravelService('MyLaravelApp', {
workers: [
{
name: 'scheduler',
scheduler: true,
},
],
});Running the Laravel Horizon
const app = new LaravelService('MyLaravelApp', {
workers: [
{
name: 'horizon',
horizon: true,
},
],
});Running custom commands
const app = new LaravelService('MyLaravelApp', {
workers: [
{
name: 'worker',
tasks: {
'scheduler': {
command: 'php artisan schedule:work',
},
'queue': {
command: 'php artisan queue:work',
},
'pulse': {
command: 'php artisan pulse:work',
},
},
},
],
});Check all the workers options here.
There are multiple ways to configure environment variables. If you want SST Laravel to copy an environment file, you can configure the config.environment.file entry.
The below configuration would copy a file named .env.$STAGE (e.g. .env.production) into the deployment containers as your .env file.
const app = new LaravelService('MyLaravelApp', {
// ...
config: {
environment: {
file: `.env.${$app.stage}`,
}
}
});You can also configure it to use simply .env.
const app = new LaravelService('MyLaravelApp', {
// ...
config: {
environment: {
file: `.env`,
}
}
});In SST, you can link resources. If you link resources to your Laravel component, SST Laravel will automatically inject and configure environment variables using sensible defaults for all the linked resources.
In the example configuration below, SST Laravel will automatically inject environment variables for the database, cache and filesystem.
const database = new sst.aws.Postgres('MyDatabase', { vpc });
const redis = new sst.aws.Redis("MyRedis", { vpc });
const bucket = new sst.aws.Bucket("MyBucket");
const app = new LaravelService('MyLaravelApp', {
link: [database, redis, bucket],
});The DB_*, REDIS_* and AWS_* environment variables will be automatically injected into your Laravel application.
You can also import existing resources into SST, in case you already have resources like databases, buckets, etc. created and in use in your AWS account.
If you need to customize the environment variable names for your resources, you can provide an object with the resource and a callback function in the link array:
const app = new LaravelService('MyLaravelApp', {
link: [
email,
{
resource: database,
environment: (database: sst.aws.Postgres) => ({
CUSTOM_DB_HOST: database.host.apply(host => host.toString()),
CUSTOM_DB_NAME: database.database.apply(database => database.toString()),
CUSTOM_DB_USER: database.username.apply(username => username.toString()),
CUSTOM_DB_PASSWORD: database.password.apply(password => password.toString()),
})
},
{
resource: redis,
environment: (redis: sst.aws.Redis) => ({
QUEUE_CONNECTION: 'redis',
QUEUE_REDIS_HOST: redis.host.apply(host => host ? `tls://${host}` : ''),
QUEUE_REDIS_PORT: redis.port.apply(port => port.toString()),
})
}
],
web: {}
});The callback function receives the resource as a parameter and should return an object with the custom environment variables. The default environment variables are still set, so you can either override them or add new ones.
If you don't want SST Laravel to auto-inject environment variables, you can disable with the following option:
config: {
environment: {
autoInject: false,
}
}The IAM permissions for the linked resources are also automatically added to the ECS IAM Execution Role, meaning your application has access to all the linked resources.
You can configure the PHP version, custom environment variables and a custom deployment script.
const app = new LaravelService('MyLaravelApp', {
config: {
php: 8.4,
opcache: true,
deployment: {
script: './infra/deploy.sh'
},
},
});Custom deployment script example:
#!/bin/sh
# Exit on error
set -e
echo "🚀 Running Deployment Script..."
cd "$APP_BASE_DIR"
echo "🚀 Running PHP Artisan Optimize..."
php artisan optimize
echo "🚀 Running Laravel Migrations..."
php artisan migrate --forceTo deploy your application, you can use the sst deploy command. You must be authenticated with AWS in your terminal session to deploy.
npx sst-laravel deploy --stage {stage}
npx sst-laravel deploy --stage sandbox
npx sst-laravel deploy --stage productionUsing the sst-laravel CLI tool, you can easily connect to your running ECS containers for debugging and troubleshooting.
npx sst-laravel ssh --stage productionThis will list all running tasks in your cluster and let you choose which one to connect to.
Connect to a specific service:
npx sst-laravel ssh web --stage production
npx sst-laravel ssh worker --stage productionIf you are naming your workers differently, you can specify the worker name:
npx sst-laravel ssh {worker-name} --stage production
npx sst-laravel ssh worker --stage production- Support for SST Secrets;
- Extend base Docker images;
- Add support for Inertia SSR;
- Add support for Octane with FrankedPHP;
- Add support for Laravel Reverb;
- Dev mode;
- ...what else are we missing?
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Development of this package is developed and sponsored by Kirschbaum Development Group, a developer driven company focused on problem solving, team building, and community. Learn more about us or join us!
The MIT License (MIT). Please see License File for more information.