Environment Variables

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.

Environment 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`,
    }
  }
});

SST Secrets

You can also use SST Secrets to store your environment variables. This is a more secure way to store your environment variables.

const APP_KEY = new sst.Secret("APP_KEY");
const DB_PASSWORD = new sst.Secret("DB_PASSWORD");

const app = new LaravelService('MyLaravelApp', {
  link: [APP_KEY, DB_PASSWORD],
});

This will automatically inject the environment variables into the .env file of your Laravel application. Read more about SST Secrets here.

AWS Secrets Manager (RemoteEnvVault)

For a more robust environment variable management solution similar to Laravel Vapor, you can use the RemoteEnvVault component. This stores your environment variables in AWS Secrets Manager and provides CLI commands to push and pull secrets.

import { RemoteEnvVault, LaravelService } from "@kirschbaum-development/sst-laravel";

const env = new RemoteEnvVault("Env");
const app = new LaravelService('MyLaravelApp', {
  // ...
  config: {
    environment: {
      secrets: env,
    }
  }
});

The secrets are stored in AWS Secrets Manager at the path /{app-name}/{stage}/env.

Large Environment Files

Large environment files that exceed AWS Secrets Manager's 64KB limit are automatically handled. The CLI will:

• Split large .env files into multiple chunks when pushing
• Automatically merge all chunks when pulling or deploying

This is completely transparent - you don't need to do anything special.

Pushing Secrets

To push your local .env file to AWS Secrets Manager:

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

# Push .env to staging (interactive)
npx sst-laravel env:push --stage staging

Pulling Secrets

To pull secrets from AWS Secrets Manager to a local file:

# Pull from production to .env.production (default)
npx sst-laravel env:pull --stage production

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

Deploying with Secrets

When using RemoteEnvVault, deploy using the sst-laravel deploy command which automatically fetches secrets before building:

npx sst-laravel deploy --stage production

Workflow Example

# 1. Initial setup - push your environment file
npx sst-laravel env:push --stage production --input .env.production

# 2. Deploy (secrets are automatically fetched)
npx sst-laravel deploy --stage production

# 3. Update secrets later
npx sst-laravel env:pull --stage production  # Creates .env.production
# Edit .env.production
npx sst-laravel env:push --stage production --input .env.production
npx sst-laravel deploy --stage production

You can also use a custom path for the secrets:

const env = new RemoteEnvVault("Env", {
  path: "/custom/path/env"
});

Resources

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.

Custom Environment Key Names

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.

Disabling the auto-inject of environment variables

If you don't want SST Laravel to auto-inject environment variables, you can disable with the following option:

config: {
  environment: {
    autoInject: false,
  }
}

IAM Roles and Permissions

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.

Other Configurations

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 --force