Skip to content

Commit d3ba88f

Browse files
aarondfrancisaarondfrancis
committed
Docs
1 parent 7272746 commit d3ba88f

17 files changed

+895
-532
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
11
# Changelog
2-
32
## Unreleased
43

4+
## 0.2.0 - 2021-07-12
5+
56
### Added
67
- New `sidecar.env` config option to separate Sidecar environment from application environment. Useful mostly for teams who have multiple developers that all have an app env of `local` and don't want to be constantly overwriting each other's functions.
78
- New `sidecar:warm` command ([#6](https://github.com/hammerstonedev/sidecar/pull/6))
89
- Better error reporting when `sidecar:deploy` is called and there are no functions.
910
- Better error reporting when a function is not found.
10-
- Implemented Sweeping to remove old, unused function versions ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
11+
- Implemented sweeping to remove old, unused function versions ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
1112
- `--pre-warm` options to `sidecar:deploy` and `sidecar:active` commands ([Commit](https://github.com/hammerstonedev/sidecar/commit/4794e6d4bfc5ddb4976c4686939ca1ee0c0ae979))
1213
- `latestVersionHasAlias` method to the LambdaClient ([Commit](https://github.com/hammerstonedev/sidecar/commit/a54f4e59aef9bfeac57ced7fb50b0c25ff268ab9))
1314

1415
### Changed
1516
- Warming is now opt-in. 0 instances are configured by default. ([Commit](https://github.com/hammerstonedev/sidecar/commit/ba53467368bcb253034fdbae7726fb0916b28de2))
1617
- Moved some methods into the Sidecar\LambdaClient ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
17-
- Break out logging & environment concerns from the Labmda Client. ([Commit](https://github.com/hammerstonedev/sidecar/commit/20e368c9773c4aae2262021c7682cf72737af270))
18+
- Break out logging & environment concerns from the Lambda Client. ([Commit](https://github.com/hammerstonedev/sidecar/commit/20e368c9773c4aae2262021c7682cf72737af270))
1819

1920
### Fixed
2021
- Allow spacing in `APP_NAME` [#17](https://github.com/hammerstonedev/sidecar/pull/17)

‎docs/configuration.md‎

Lines changed: 40 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,35 @@
11

22
# Configuring Sidecar
33

4-
## Configuring AWS
4+
After running `php artisan sidecar:install`, you should have a `sidecar.php` file in your `config` folder.
5+
6+
There are several configuration options in that file, which we'll cover in this section.
7+
8+
## AWS Credentials
59

610
Sidecar requires a few very specific things be set up in your AWS in order to have the proper permissions to deploy and execute your functions.
711

8-
In order to save you from the frustration of AWS IAM, we have written a single, interactive command that can handle everything for you.
12+
In order to save you from the frustration of using AWS IAM we have written a single, interactive command that can handle everything for you.
913

1014
To get started, run the following command:
1115

12-
```text
16+
```shell
1317
php artisan sidecar:configure
1418
```
1519

16-
The first thing it will do is guide you through creating a new AWS user, which it will then use to create everything else it needs.
20+
The first thing it will do is guide you through creating a new AWS user in the web interface, which it will then use to create everything else it needs.
1721

1822
Note that this won't start any services, it just creates some policies in IAM.
1923

20-
This is the same method that Vapor uses: you provide it with Admin Access and then it configures itself.
24+
This is the same general method that Laravel Vapor uses: you provide it with Admin Access and then it configures itself. Sidecar takes it a step further and provides you the option to self-destruct the admin keys once it has configured itself.
2125

2226
If you'd like to manually set everything up, take a look at the command to see exactly what it's doing, and you can recreate it in the IAM portal.
2327

2428
## Registering Functions
2529

2630
Each function that you make will need to be registered in the `functions` key of your `sidecar.php`
2731

28-
sidecar.php {.filename}
32+
config/sidecar.php {.filename}
2933
```php
3034
return [
3135
/*
@@ -35,45 +39,15 @@ return [
3539
\App\Sidecar\OgImage::class,
3640
\App\Sidecar\ProcessThumbnail::class,
3741
],
38-
// [tl! collapse-start closed]
39-
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
40-
* *
41-
* You are welcome to edit this configuration directly, or you can run *
42-
* `php artisan sidecar:configure` for an interactive walk-through. *
43-
* *
44-
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
45-
46-
/*
47-
* Your AWS key. See CreateDeploymentUser::policy for the IAM policy.
48-
*
49-
* Unfortunately you cannot rely on the keys available in the Vapor
50-
* runtime, as those do not have the right permissions.
51-
*/
52-
'aws_key' => env('SIDECAR_ACCESS_KEY_ID'),
53-
54-
/*
55-
* Your AWS secret key.
56-
*/
57-
'aws_secret' => env('SIDECAR_SECRET_ACCESS_KEY'),
58-
59-
/*
60-
* The region where your Lambdas will be deployed.
61-
*/
62-
'aws_region' => env('SIDECAR_REGION'),
42+
];
43+
```
6344

64-
/*
65-
* The bucket that temporarily holds your function's ZIP files as they
66-
* are deployed to Lambda. It must be the same region as your Lambdas.
67-
*/
68-
'aws_bucket' => env('SIDECAR_ARTIFACT_BUCKET_NAME'),
45+
## Function Timeout & Memory
6946

70-
/*
71-
* This is the execution role that your Lambdas will use.
72-
*
73-
* See CreateExecutionRole::policy for the IAM policy.
74-
*/
75-
'execution_role' => env('SIDECAR_EXECUTION_ROLE'),
47+
The timeout and memory can be customized on a per-function basis, but if they aren't, the defaults from your `sidecar.php` file will be used.
7648

49+
```php
50+
return [
7751
/*
7852
* The default timeout for your functions, in seconds.
7953
* This can be overridden per function.
@@ -84,94 +58,47 @@ return [
8458
* The default memory for your functions, in megabytes.
8559
* This can be overridden per function.
8660
*/
87-
'memory' => env('SIDECAR_MEMORY', 512),
88-
89-
/*
90-
* The base path for your package files. If you e.g. keep
91-
* all your Lambda package files in your resource path,
92-
* you may change the base path here.
93-
*/
94-
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()), // [tl! collapse-end]
61+
'memory' => env('SIDECAR_MEMORY', 512),
9562
];
9663
```
9764

98-
## Default Settings
99-
100-
The timeout and memory can be customized on a per-function basis, but if they aren't, the defaults from your `sidecar.php` file will be used.
101-
102-
### Package Base Path
65+
## Package Base Path
10366

10467
By default, all of your Lambda resources are going to be relative to the `base_path()` of your application. That means when you're defining your code packages, you'll use the root of your application as the starting point.
10568

10669
If all of your Lambda code lives in e.g. `resources/lambda`, then you can update your `package_base_path` to reflect that.
10770

108-
sidecar.php {.filename}
71+
config/sidecar.php {.filename}
10972
```php
11073
return [
111-
// [tl! collapse-start closed]
112-
/*
113-
* All of your function classes that you'd like to deploy go here.
114-
*/
115-
'functions' => [
116-
\App\Sidecar\OgImage::class,
117-
\App\Sidecar\ProcessThumbnail::class,
118-
],
119-
120-
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
121-
* *
122-
* You are welcome to edit this configuration directly, or you can run *
123-
* `php artisan sidecar:configure` for an interactive walk-through. *
124-
* *
125-
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
126-
12774
/*
128-
* Your AWS key. See CreateDeploymentUser::policy for the IAM policy.
129-
*
130-
* Unfortunately you cannot rely on the keys available in the Vapor
131-
* runtime, as those do not have the right permissions.
75+
* The base path for your package files. If you e.g. keep
76+
* all your Lambda package files in your resource path,
77+
* you may change the base path here.
13278
*/
133-
'aws_key' => env('SIDECAR_ACCESS_KEY_ID'),
79+
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()),
80+
];
81+
```
13482

135-
/*
136-
* Your AWS secret key.
137-
*/
138-
'aws_secret' => env('SIDECAR_SECRET_ACCESS_KEY'),
83+
This is also configurable on a per-function basis. To learn more about that, see the [Handlers & Packages](/functions/handlers-and-packages) section.
13984

140-
/*
141-
* The region where your Lambdas will be deployed.
142-
*/
143-
'aws_region' => env('SIDECAR_REGION'),
85+
## Environment
14486

145-
/*
146-
* The bucket that temporarily holds your function's ZIP files as they
147-
* are deployed to Lambda. It must be the same region as your Lambdas.
148-
*/
149-
'aws_bucket' => env('SIDECAR_ARTIFACT_BUCKET_NAME'),
87+
Sidecar separates functions by environment so that your development, staging, and production functions do not overwrite each other.
15088

151-
/*
152-
* This is the execution role that your Lambdas will use.
153-
*
154-
* See CreateExecutionRole::policy for the IAM policy.
155-
*/
156-
'execution_role' => env('SIDECAR_EXECUTION_ROLE'),
157-
// [tl! collapse-end]
158-
/*
159-
* The default timeout for your functions, in seconds.
160-
* This can be overridden per function.
161-
*/
162-
'timeout' => env('SIDECAR_TIMEOUT', 300),
89+
By default, the environment name that Sidecar uses is your `APP_ENV` from your `.env` file. This usually works great for staging and production, but if you are working on a team, you'll have multiple people using an environment named `local`, potentially interfering with one another.
16390

164-
/*
165-
* The default memory for your functions, in megabytes.
166-
* This can be overridden per function.
167-
*/
168-
'memory' => env('SIDECAR_MEMORY', 512),
91+
If you'd like to use something other than the `APP_ENV`, you can do so by providing a `SIDECAR_ENV` environment variable.
16992

170-
/*
171-
* The base path for your package files. If you e.g. keep
172-
* all your Lambda package files in your resource path,
173-
* you may change the base path here.
93+
```php
94+
return [
95+
/*
96+
* Sidecar separates functions by environment. If you'd like to change
97+
* your Sidecar environment without changing your entire application
98+
* environment, you may do so here.
17499
*/
175-
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()),
100+
'env' => env('SIDECAR_ENV', env('APP_ENV')),
176101
];
177-
```
102+
```
103+
104+
To learn much more about environments and how to use them, see the [Environments](/environments) section.

‎docs/environments.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
2+
# Environments
3+
4+
Sidecar functions are separated by environment, so that your local development functions don't overwrite your production functions. You can have as many environments as you please.
5+
6+
By default, Sidecar will use the environment from your Laravel application, which itself comes from the `APP_ENV` environment variable.
7+
8+
If you'd rather use a dedicated environment variable for Sidecar, you can use the `SIDECAR_ENV` variable.
9+
10+
```php
11+
<?php
12+
13+
return [
14+
/*
15+
* Sidecar separates functions by environment. If you'd like to change
16+
* your Sidecar environment without changing your entire application
17+
* environment, you may do so here.
18+
*/
19+
'env' => env('SIDECAR_ENV', env('APP_ENV')),
20+
];
21+
```
22+
23+
This can be particularly useful when you're developing in a team. If everyone on your team has `APP_ENV=local` in their environment file, then it's likely that functions will inadvertently be overwritten by your teammates, which is both confusing and frustrating.
24+
25+
In this case, it would make sense to set your Sidecar environment to e.g. `SIDECAR_ENV=aaron_local`, `SIDECAR_ENV=sean_local`, etc.
26+
27+
This way Sean & Aaron have different environments and won't overwrite each other's work.
28+
29+
## Faking the Environment
30+
31+
If you need to deploy an environment other than the one you are in, you can override the environment from the config by passing an `--env` flag to the Deploy and Activate commands.
32+
33+
```shell
34+
php artisan sidecar:deploy --env=production
35+
php artisan sidecar:activate --env=production
36+
```
37+
38+
This is useful when you want to build and deploy from either your local machine, your CI pipeline, or GitHub Actions, and then you want to activate as your Laravel application rolls out.
39+
40+
Head over to the [Deploying section](functions/deploying) to read more about activating & deploying your functions.

0 commit comments

Comments
 (0)