@kirschbaum-development/sst-laravel 0.2.14 → 0.2.16

package/docs/api.md

@@ -0,0 +1,597 @@
+# 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
+
+```typescript
+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:**
+```typescript
+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.
+
+```bash
+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:**
+```bash
+# 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.
+
+```bash
+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:**
+```bash
+# 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
+
+```typescript
+const env = new RemoteEnvVault("Env");
+
+new LaravelService("Laravel", {
+  vpc,
+  web: {
+    domain: "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:
+
+```bash
+sst-laravel deploy --stage production
+```
+
+---
+
+## LaravelService
+
+### Constructor
+
+```typescript
+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.
+
+### `link`
+- **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:
+
+```typescript
+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:**
+```typescript
+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):**
+```typescript
+web: {
+  domain: "example.com"
+}
+```
+
+**Example (with stage variable):**
+```typescript
+web: {
+  domain: {
+    name: `${$app.stage}.example.com`
+  }
+}
+```
+
+**Example (with custom certificate):**
+```typescript
+web: {
+  domain: {
+    name: "example.com",
+    cert: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"
+  }
+}
+```
+
+**Example (with custom DNS provider):**
+```typescript
+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:**
+```typescript
+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:** Health check configuration for the web service.
+
+#### `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:**
+```typescript
+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.
+
+### `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:**
+```typescript
+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:**
+```typescript
+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:**
+```typescript
+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:**
+```typescript
+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:**
+```typescript
+const app = new LaravelService("MyApp", { ... });
+console.log(app.url); // https://example.com or https://xyz.elb.amazonaws.com
+```
+
+## Complete Example
+
+```typescript
+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
+    }
+  },
+  
+  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
+};
+```
+
+## Example with RemoteEnvVault (Secrets Manager)
+
+```typescript
+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
+    }
+  },
+  
+  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,
+  secretsPath: env.path
+};
+```
+
+### Workflow with RemoteEnvVault
+
+1. **Initial setup** - Push your `.env` file to AWS Secrets Manager:
+   ```bash
+   sst-laravel env:push --stage production --input .env.production
+   ```
+
+2. **Deploy** - Use the sst-laravel CLI to deploy (automatically fetches secrets):
+   ```bash
+   sst-laravel deploy --stage production
+   ```
+
+3. **Update secrets** - When you need to update environment variables:
+   ```bash
+   # 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
+   ```

package/laravel-sst.ts

@@ -537,7 +537,7 @@ export class LaravelService extends Component {
             return {
                 id: vpc.id,
                 securityGroups: vpc.securityGroups,
-                containerSubnets: vpc.publicSubnets,
+                containerSubnets: vpc.privateSubnets,
                 loadBalancerSubnets: vpc.publicSubnets,
                 cloudmapNamespaceId: cloudmapNamespace.id,
                 cloudmapNamespaceName: cloudmapNamespace.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirschbaum-development/sst-laravel",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "type": "module",
   "description": "An unofficial extension of SST to deploy containerized Laravel applications to AWS Fargate.",
   "main": "laravel-sst.ts",
@@ -19,6 +19,8 @@
     "templates",
     "conf",
     "images",
+    "docs",
+    "README.md",
     "Dockerfile.web",
     "Dockerfile.worker",
     ".dockerignore",
@@ -26,6 +28,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "release": "./scripts/publish.sh"
   },
   "repository": {
@@ -63,7 +66,8 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "4.1.5"
   },
   "publishConfig": {
     "access": "public",

package/src/remote-env-file.ts

@@ -213,19 +213,38 @@ function buildEnvFileContent(
   ].filter(Boolean).join('\n\n');
 }
 
-function toEnvFileContent(vars: Record<string, string>): string {
+export function toEnvFileContent(vars: Record<string, string>): string {
   const sortedKeys = Object.keys(vars).sort();
 
   return sortedKeys
     .map((key) => {
       const value = vars[key];
+      const needsQuoting =
+        value.includes(' ') ||
+        value.includes('"') ||
+        value.includes("'") ||
+        value.includes('\n') ||
+        value.includes('$') ||
+        value.includes('\\') ||
+        value.includes('#');
+
+      if (!needsQuoting) {
+        return `${key}=${value}`;
+      }
 
-      if (value.includes(' ') || value.includes('"') || value.includes("'") || value.includes('\n')) {
-        const escaped = value.replace(/"/g, '\\"');
-        return `${key}="${escaped}"`;
+      // Single quotes are phpdotenv "raw literal" mode — no $ expansion, no escapes.
+      // Use them whenever possible so randomly-generated secrets round-trip safely.
+      if (!value.includes("'") && !value.includes('\n')) {
+        return `${key}='${value}'`;
       }
 
-      return `${key}=${value}`;
+      // Fall back to double quotes when the value itself contains a single quote
+      // or newline. Escape \, $, and " so phpdotenv reads the literal value.
+      const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/\$/g, '\\$')
+        .replace(/"/g, '\\"');
+      return `${key}="${escaped}"`;
     })
     .join('\n');
 }