Docs [ci skip]

Author: aarondfrancis

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 ## Unreleased 
 
+## 0.3.0 - 2021-07-20
+
+### Added
+
+- Support for Lambda environment variables ([#25](https://github.com/hammerstonedev/sidecar/pull/25))
+
 ## 0.2.0 - 2021-07-12 
 
 ### Added

docs/functions/customization.md

@@ -114,7 +114,7 @@ Note that your layers must be in the same AWS region as your Lambdas!
 
 ## Environment Variables
 
-Some functions or layers may require configuration via Lambda environment variables. The Lambda runtime makes environment variables available to the code.
+Some functions or layers may require configuration via Lambda environment variables. The Lambda runtime will inject the environment variables so that they available to your handler code.
 
 In this example below, we're providing a path to a font directory as an environment variable.
 ```php
@@ -145,7 +145,7 @@ By default, Sidecar doesn't touch your Lambda's environment at all. Only when yo
 
 Another important thing to note is that Sidecar sets your environment variables as a part of the _activation_ process, not the _deploy_ process. This means that the environment variables will be pulled from the machine that calls `sidecar:activate`.
 
-For example, if you are sharing secrets with your Lambda, then the values passed to your Lambda will be equal to the ones on the machine that called `sidecar:activate`, not the one that called `sidecar:deploy`:
+For example, if you are sharing secrets with your Lambda, then the values passed to your Lambda will be equal to the ones on the machine that called `sidecar:activate`, not the one that called `sidecar:deploy`
 
 ```php
 class ExampleFunction extends LambdaFunction
@@ -171,6 +171,8 @@ class ExampleFunction extends LambdaFunction
 }
 ```
 
+This is obviously important when you are calling `deploy` and `activate` from different machines as a part of your Laravel application's deployment process. To read more about deployment strategies, check out the [deploying](deploying) section.
+
 ## Name
 
 Your function has a `name` method that determines how Sidecar names your Lambda functions. By default it is based on the name and path of your PHP class. You are free to change this if you want, but you're unlikely to need to.

docs/functions/deploying.md

@@ -94,6 +94,73 @@ php artisan sidecar:activate --env=production
 
 To read more about environments, head to the [Environments section](../environments) of the docs.
 
+## Setting Environment Variables
+
+This is covered in the [Environment Variables](customization#environment-variables) section of the Customization docs, but we'll cover strategies around env vars and deployment here. 
+
+Some of your functions will require environment variables, either from your Laravel application or something completely distinct. In some cases, you may need to set a static variable so that some library will work [(LibreOffice example)](https://github.com/hammerstonedev/sidecar/issues/24):
+
+```php
+// torchlight! {"summaryCollapsedIndicator": "{ ... }" }
+class ExampleFunction extends LambdaFunction
+{
+    public function handler() // [tl! collapse:start]
+    {
+        //
+    }
+
+    public function package()
+    {
+        //
+    } // [tl! collapse:end]
+
+    public function variables()
+    {
+        return [
+            'FONTCONFIG_PATH' => '/opt/etc/fonts',
+        ];
+    }
+}
+```
+
+Setting static variables like that is quite straightforward.
+
+If, however, you want to share some secrets or environment variables _from your Laravel_ application, it will be important that you are sharing them from the correct environment.
+
+Imagine the scenario where you want to share your AWS keys with your Lambda function:
+
+```php
+// torchlight! {"summaryCollapsedIndicator": "{ ... }" }
+class ExampleFunction extends LambdaFunction
+{
+    public function handler() // [tl! collapse:start]
+    {
+        //
+    }
+
+    public function package()
+    {
+        //
+    } // [tl! collapse:end]
+
+    public function variables()
+    {
+        return [
+            'aws_key' => config('services.aws.key'),
+            'aws_secret' => config('services.aws.secret'),
+        ];
+    }
+}
+```
+
+You pull your key and secret using the Laravel `config` function, which in turn likely delegates to the `env()` function.
+
+Sidecar sets the environment variables _upon activation_. If you are deploying from CI and then activating from e.g. Vapor, you'll want to make sure you have those variables in the Vapor environment.
+
+Environment variables are set before activation, and before any pre-warming takes place.
+
+And remember! If Sidecar manages the environment variables for a function, it will clobber any changes you make in the AWS UI, so you cannot use both methods simultaneously.  
+
 ## Reusing Package Files
 
 If you're deploying your Sidecar functions every time you deploy your app, you will likely be deploying functions that have not changed at all.