Skip to main content

Laravel Component API Reference

RemoteEnvVault​

The RemoteEnvVault component manages environment variables for your Laravel application using AWS Secrets Manager. This provides a secure way to store and manage sensitive configuration values.

Large Environment Files​

Environment files that exceed AWS Secrets Manager's 64KB limit are automatically split into multiple chunks. This is handled transparently by the CLI commands - you don't need to do anything special.

When pushing a large .env file:

  • The file is automatically split into multiple secrets (e.g., /{app}/{stage}/env/1, /{app}/{stage}/env/2, etc.)
  • A metadata secret at /{app}/{stage}/env tracks the chunk count
  • When pulling or deploying, all chunks are automatically merged back together

Constructor​

new RemoteEnvVault(name: string, args?: RemoteEnvVaultArgs, opts?: ComponentResourceOptions)

RemoteEnvVaultArgs​

path​

  • Type: Input<string>
  • Default: /{app-name}/{stage}/env
  • Description: The path in AWS Secrets Manager where environment variables will be stored.

Example:

const env = new RemoteEnvVault("Env", {
  path: "/my-app/production/env"
});

Properties​

path​

  • Type: Output<string>
  • Description: The path in AWS Secrets Manager where environment variables are stored.

CLI Commands​

The following CLI commands are available for managing environment variables:

env:push​

Push environment variables from a local .env file to AWS Secrets Manager.

sst-laravel env:push [options]

Options:

  • -s, --stage <stage> - SST stage name
  • -i, --input <file> - Input file path (default: .env)
  • -f, --force - Push without confirmation

Example:

# Push .env.production to the production stage
sst-laravel env:push --stage production --input .env.production

# Push .env to staging with confirmation
sst-laravel env:push --stage staging

env:pull​

Pull environment variables from AWS Secrets Manager to a local .env file.

sst-laravel env:pull [options]

Options:

  • -s, --stage <stage> - SST stage name
  • -o, --output <file> - Output file path (default: .env.{stage})
  • -f, --force - Overwrite existing file without confirmation

Example:

# Pull from production to .env.production
sst-laravel env:pull --stage production

# Pull from staging to a custom file
sst-laravel env:pull --stage staging --output .env.local

Usage with LaravelService​

const env = new RemoteEnvVault("Env");

new LaravelService("Laravel", {
  vpc,
  web: {
    domain: "example.com"
  },
  reverb: {
    domain: "ws.example.com"
  },
  config: {
    environment: {
      secrets: env
    }
  }
});

When using RemoteEnvVault, deploy your application using the sst-laravel deploy command, which will automatically fetch secrets from AWS Secrets Manager before building the Docker image:

sst-laravel deploy --stage production

LaravelService​

Constructor​

new LaravelService(name: string, args: LaravelArgs, opts?: ComponentResourceOptions)

Creates a new Laravel component for deploying Laravel applications to AWS Fargate.

LaravelArgs​

path​

  • Type: Input<string>
  • Default: '.'
  • Description: Path to the Laravel application directory.
  • Type: Array<Resource | { resource: Resource; environment?: EnvCallback }>
  • Description: Resources to link to the Laravel application. Supports SST resources like databases, Redis, email services, queues, and S3 buckets. When linked, environment variables are automatically configured.

Supported resources with automatic environment variable injection:

  • Postgres - Sets DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_PORT
  • Mysql - Sets DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD, DB_PORT
  • Aurora - Sets database variables based on port (5432 for Postgres, 3306 for MySQL)
  • Redis - Sets REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
  • Email - Sets MAIL_MAILER to 'ses'
  • Queue - Sets SQS_QUEUE
  • Bucket - Sets FILESYSTEM_DISK to 's3', AWS_BUCKET

You can provide a custom environment callback function to override or extend the default environment variables:

link: [
  {
    resource: myDatabase,
    environment: (resource) => ({
      CUSTOM_DB_VAR: resource.host
    })
  }
]

permissions​

  • Type: Array<{ actions: string[]; resources: string[] }>
  • Description: IAM permissions to grant to the Laravel application containers.

Example:

permissions: [
  {
    actions: ["s3:GetObject", "s3:PutObject"],
    resources: ["arn:aws:s3:::my-bucket/*"]
  }
]

vpc​

  • Type: ClusterArgs["vpc"]
  • Description: VPC configuration for the ECS cluster. Inherited from SST's Cluster component.

web​

  • Type: LaravelWebArgs
  • Description: Configuration for the web service that handles HTTP traffic.

web.domain​

  • Type: Input<string | { name: Input<string>; cert?: Input<string>; dns?: Input<false | Dns> }>
  • Description: Custom domain for the web layer. If you don't provide a domain name, you will be able to use the load balancer domain for testing (http only).

Example (simple string):

web: {
  domain: "example.com"
}

Example (with stage variable):

web: {
  domain: {
    name: `${$app.stage}.example.com`
  }
}

Example (with custom certificate):

web: {
  domain: {
    name: "example.com",
    cert: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"
  }
}

Example (with custom DNS provider):

web: {
  domain: {
    name: "example.com",
    dns: sst.cloudflare.dns()
  }
}

web.architecture​

  • Type: ServiceArgs["architecture"]
  • Description: The CPU architecture for the web service.

web.cpu​

  • Type: ServiceArgs["cpu"]
  • Description: CPU units for the web service.

web.memory​

  • Type: ServiceArgs["memory"]
  • Description: Memory allocation for the web service.

web.storage​

  • Type: ServiceArgs["storage"]
  • Description: Storage configuration for the web service.

web.scaling​

  • Type: ServiceArgs["scaling"]
  • Description: Auto-scaling configuration for the web service.

Example:

web: {
  scaling: {
    min: 2,
    max: 10,
    cpuUtilization: 70,
    memoryUtilization: 80
  }
}

web.logging​

  • Type: ServiceArgs["logging"]
  • Description: Logging configuration for the web service.

web.health​

  • Type: ServiceArgs["health"]
  • Description: ECS container-level health check for the web service. Distinct from web.healthCheck (load balancer).

web.healthCheck​

  • Type: Input<LaravelHealthCheck>
  • Description: Load balancer health check applied to the default forward port (8080/http). Shorthand so you don't have to override the full loadBalancer config just to set a path. Ignored when loadBalancer is provided — configure loadBalancer.health directly in that case.

Example:

web: {
  domain: { name: 'app.example.com' },
  healthCheck: {
    path: '/up',
    successCodes: '200',
    interval: '30 seconds',
    healthyThreshold: 2,
    unhealthyThreshold: 3,
  },
}

web.httpsRedirect​

  • Type: boolean
  • Default: true
  • Description: When a domain is configured, redirect HTTP (port 80) traffic to the HTTPS (port 443) listener instead of forwarding it straight to the application. Set to false to keep forwarding HTTP traffic to the app. Has no effect when no domain is set (there is no HTTPS listener to redirect to) or when an explicit loadBalancer is provided.

Example:

web: {
  domain: { name: 'app.example.com' },
  httpsRedirect: false,
}

web.accessLogs​

  • Type: boolean
  • Default: true
  • Description: Stream the nginx access logs from the web container to CloudWatch. The web container runs nginx (serversideup/php:*-fpm-nginx), which logs every request — including the load balancer health-check pings — to stdout. Set to false to silence those access logs (points the serversideup NGINX_ACCESS_LOG variable at /dev/null). Error logs and the Laravel application logs are unaffected. Only the web container runs nginx, so this has no effect on workers or the Reverb service.

Example:

web: {
  accessLogs: false,
}

web.horizon​

  • Type: Input<boolean>
  • Default: false
  • Description: Run Laravel Horizon (php artisan horizon) as a supervised background process inside the web container, alongside nginx and PHP-FPM. If the process crashes, s6 restarts it in place without interrupting HTTP traffic.

web.scheduler​

  • Type: Input<boolean>
  • Default: false
  • Description: Run the Laravel scheduler (php artisan schedule:work) as a supervised background process inside the web container. If the web service scales beyond one container, every replica runs the scheduler — use onOneServer() with a shared cache store on your scheduled jobs.

web.tasks​

  • Type: Input<{ [key: string]: Input<{ command: Input<string>; dependencies?: Input<string[]> }> }>
  • Description: Custom long-running commands supervised inside the web container, keyed by task name.

Example:

web: {
  horizon: true,
  scheduler: true,
  tasks: {
    pulse: {
      command: "php artisan pulse:work"
    }
  }
}

web.executionRole​

  • Type: ServiceArgs["executionRole"]
  • Description: Execution role for the web service.

web.permissions​

  • Type: ServiceArgs["permissions"]
  • Description: IAM permissions specific to the web service.

workers​

  • Type: LaravelWorkerConfig[]
  • Description: Configuration for worker services (Horizon, scheduler, or custom tasks).

workers[].name​

  • Type: Input<string>
  • Description: Name of the worker service. If not provided, defaults to worker-{index}.

workers[].horizon​

  • Type: Input<boolean>
  • Default: false
  • Description: Running horizon?

workers[].scheduler​

  • Type: Input<boolean>
  • Default: false
  • Description: Running scheduler?

workers[].tasks​

  • Type: Input<{ [key: string]: Input<{ command: Input<string>; dependencies?: Input<string[]> }> }>
  • Description: Multiple tasks can be run in the worker.

Example:

workers: [
  {
    name: "main-worker",
    horizon: true,
    scheduler: true,
    scaling: {
      min: 1,
      max: 5
    }
  },
  {
    name: "custom-worker",
    tasks: {
      "my-task": {
        command: "php artisan my:command",
        dependencies: ["laravel-horizon"]
      }
    }
  }
]

workers[].architecture​

  • Type: ServiceArgs["architecture"]
  • Description: The CPU architecture for the worker service.

workers[].cpu​

  • Type: ServiceArgs["cpu"]
  • Description: CPU units for the worker service.

workers[].memory​

  • Type: ServiceArgs["memory"]
  • Description: Memory allocation for the worker service.

workers[].storage​

  • Type: ServiceArgs["storage"]
  • Description: Storage configuration for the worker service.

workers[].scaling​

  • Type: ServiceArgs["scaling"]
  • Description: Auto-scaling configuration for the worker service.

workers[].logging​

  • Type: ServiceArgs["logging"]
  • Description: Logging configuration for the worker service.

workers[].health​

  • Type: ServiceArgs["health"]
  • Description: Health check configuration for the worker service.

workers[].executionRole​

  • Type: ServiceArgs["executionRole"]
  • Description: Execution role for the worker service.

workers[].permissions​

  • Type: ServiceArgs["permissions"]
  • Description: IAM permissions specific to this worker.

reverb​

  • Type: boolean | LaravelReverbArgs
  • Default: false
  • Description: Configuration for a dedicated Laravel Reverb service. When enabled, SST Laravel creates a worker-style service that runs php artisan reverb:start and exposes it through a load balancer.

Example:

reverb: {
  domain: "ws.example.com",
  scaling: {
    min: 1,
    max: 2
  }
}

You can also enable Reverb with defaults:

reverb: true

reverb.domain​

  • Type: Input<string | { name: Input<string>; cert?: Input<string>; dns?: Input<false | Dns> }>
  • Description: Custom domain for the Reverb service. If provided, SST Laravel routes HTTP and HTTPS traffic to Reverb's internal listener on port 8080 by default.

Example (with custom DNS provider):

reverb: {
  domain: {
    name: "ws.example.com",
    dns: sst.cloudflare.dns()
  }
}

When reverb.domain is configured, SST Laravel auto-injects:

REVERB_SERVER_HOST=0.0.0.0
REVERB_SERVER_PORT=8080
REVERB_HOST=ws.example.com
REVERB_PORT=443
REVERB_SCHEME=https

reverb.host​

  • Type: string
  • Default: "0.0.0.0"
  • Description: Host the Reverb server listens on inside the container.

reverb.port​

  • Type: number
  • Default: 8080
  • Description: Port the Reverb server listens on inside the container. The default load balancer forwards traffic to this port.

reverb.command​

  • Type: string
  • Default: "php artisan reverb:start"
  • Description: Command used to start the Reverb service.

reverb.architecture​

  • Type: ServiceArgs["architecture"]
  • Description: The CPU architecture for the Reverb service.

reverb.cpu​

  • Type: ServiceArgs["cpu"]
  • Description: CPU units for the Reverb service.

reverb.memory​

  • Type: ServiceArgs["memory"]
  • Description: Memory allocation for the Reverb service.

reverb.storage​

  • Type: ServiceArgs["storage"]
  • Description: Storage configuration for the Reverb service.

reverb.scaling​

  • Type: ServiceArgs["scaling"]
  • Description: Auto-scaling configuration for the Reverb service. Horizontal Reverb scaling requires Redis and REVERB_SCALING_ENABLED=true in your Laravel environment.

reverb.logging​

  • Type: ServiceArgs["logging"]
  • Description: Logging configuration for the Reverb service.

reverb.health​

  • Type: ServiceArgs["health"]
  • Description: ECS health check configuration for the Reverb service.

reverb.executionRole​

  • Type: ServiceArgs["executionRole"]
  • Description: Execution role for the Reverb service.

reverb.permissions​

  • Type: ServiceArgs["permissions"]
  • Description: IAM permissions specific to the Reverb service.

config​

  • Type: object
  • Description: Config settings.

config.php​

  • Type: Input<Number>
  • Default: 8.4
  • Description: PHP version. Available versions: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5

config.opcache​

  • Type: Input<boolean>
  • Default: true
  • Description: PHP Opcache should be enabled?

config.environment​

  • Type: object
  • Description: Environment variable configuration.
config.environment.file​
  • Type: Input<string>
  • Description: Use this option if you want to import an .env file during build. By default, SST Laravel won't use your .env file since that might be the wrong file when deploying from your local machine.

Example:

config: {
  environment: {
    file: `.env.${$app.stage}`
  }
}
config.environment.autoInject​
  • Type: Input<boolean>
  • Default: true
  • Description: Set this to false in case you don't want to auto inject environment variables from your linked resources.
config.environment.vars​
  • Type: FunctionArgs["environment"]
  • Description: Custom environment variables that will be automatically injected into your application.

Example:

config: {
  environment: {
    vars: {
      SESSION_DRIVER: 'redis',
      QUEUE_CONNECTION: 'redis',
      LOG_CHANNEL: 'stderr'
    }
  }
}
config.environment.secrets​
  • Type: RemoteEnvVault
  • Description: Use a RemoteEnvVault component to manage environment variables in AWS Secrets Manager. When provided, secrets will be fetched from AWS Secrets Manager at build time using the sst-laravel deploy command.

Example:

const env = new RemoteEnvVault("Env");

new LaravelService("Laravel", {
  config: {
    environment: {
      secrets: env
    }
  }
});

Note: When using secrets, you should deploy using sst-laravel deploy --stage <stage> instead of sst deploy directly. This ensures secrets are fetched from AWS Secrets Manager before the Docker build.

config.deployment​

  • Type: object
  • Description: Custom deployment configurations.
config.deployment.script​
  • Type: Input<string>
  • Description: Path to a custom deployment script to run during container startup.

Example:

config: {
  deployment: {
    script: "./deploy.sh"
  }
}

Properties​

url​

  • Type: Output<string>
  • Description: The URL of the web service. If web.domain is set, returns the custom domain URL. Otherwise, returns the auto-generated load balancer URL.

Example:

const app = new LaravelService("MyApp", { ... });
console.log(app.url); // https://example.com or https://xyz.elb.amazonaws.com

reverbUrl​

  • Type: Output<string>
  • Description: The URL of the Reverb service. If reverb.domain is set, returns the custom domain URL. Otherwise, returns the auto-generated load balancer URL.

Example:

const app = new LaravelService("MyApp", { ... });
console.log(app.reverbUrl); // https://ws.example.com or https://xyz.elb.amazonaws.com

Complete Example​

const vpc = new sst.aws.Vpc("MyVpc");
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("MyApp", {
  path: "./",
  vpc,
  
  link: [database, redis, bucket],
  
  permissions: [
    {
      actions: ["s3:*"],
      resources: [bucket.arn, `${bucket.arn}/*`]
    }
  ],
  
  web: {
    domain: "example.com",
    scaling: {
      min: 2,
      max: 10
    }
  },

  reverb: {
    domain: "ws.example.com",
    scaling: {
      min: 1,
      max: 2
    }
  },
  
  workers: [
    {
      name: "queue-worker",
      horizon: true,
      scheduler: true,
      scaling: {
        min: 1,
        max: 5
      }
    }
  ],
  
  config: {
    php: 8.4,
    opcache: true,
    
    environment: {
      file: `.env.${$app.stage}`,
      autoInject: true,
      vars: {
        SESSION_DRIVER: 'redis',
        QUEUE_CONNECTION: 'redis'
      }
    },
    
    deployment: {
      script: "./deploy.sh"
    }
  }
});

return {
  url: app.url,
  reverbUrl: app.reverbUrl
};

Example with RemoteEnvVault (Secrets Manager)​

const vpc = new sst.aws.Vpc("MyVpc");
const database = new sst.aws.Postgres("MyDatabase", { vpc });
const redis = new sst.aws.Redis("MyRedis", { vpc });

// Create environment secrets manager
const env = new RemoteEnvVault("Env");

const app = new LaravelService("MyApp", {
  path: "./",
  vpc,
  
  link: [database, redis],
  
  web: {
    domain: "example.com",
    scaling: {
      min: 2,
      max: 10
    }
  },

  reverb: {
    domain: "ws.example.com"
  },
  
  workers: [
    {
      name: "queue-worker",
      horizon: true,
      scheduler: true
    }
  ],
  
  config: {
    php: 8.4,
    
    environment: {
      // Use secrets from AWS Secrets Manager
      secrets: env,
      // Auto-inject linked resource variables (database, redis)
      autoInject: true,
      // Additional runtime variables
      vars: {
        SESSION_DRIVER: 'redis',
        QUEUE_CONNECTION: 'redis'
      }
    }
  }
});

return {
  url: app.url,
  reverbUrl: app.reverbUrl,
  secretsPath: env.path
};

Workflow with RemoteEnvVault​

  1. Initial setup - Push your .env file to AWS Secrets Manager:

    sst-laravel env:push --stage production --input .env.production

  2. Deploy - Use the sst-laravel CLI to deploy (automatically fetches secrets):

    sst-laravel deploy --stage production

  3. Update secrets - When you need to update environment variables:

    # Pull current secrets (creates .env.production by default)
    sst-laravel env:pull --stage production

    # Edit the file
    nano .env.production

    # Push updated secrets
    sst-laravel env:push --stage production --input .env.production

    # Redeploy to apply changes
    sst-laravel deploy --stage production