Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOCS] Revamp websites docs to use Lift #1060

Merged
merged 6 commits into from
Oct 24, 2021
Merged

[DOCS] Revamp websites docs to use Lift #1060

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7fe2915
[DOCS] Revamp websites docs
t-richard Oct 17, 2021
a1ceb31
Remove useless images
t-richard Oct 17, 2021
e2625a8
Remove yet another useless image
t-richard Oct 17, 2021
4ebbef1
Address review comments
t-richard Oct 18, 2021
4fc8f77
Some more fixes
t-richard Oct 19, 2021
94e9fd3
Update cloudfront image
t-richard Oct 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ This matrix will be updated as Bref and AWS services evolve over time.

- **Website**

Websites can run on AWS Lambda. Assets can be served via AWS S3. That requires a bit of setup but this is documented in the ["Websites" documentation](/docs/websites.md). Performance is as good as any server.
Websites can run on AWS Lambda. Assets can be stored in S3 and served via Cloudfront. This is documented in the ["Websites" documentation](/docs/websites.md). Performance is as good as any server.

- **Legacy application**

Expand Down
Binary file removed docs/cloudfront.png
View file
Open in desktop
Binary file not shown.
30 changes: 4 additions & 26 deletions docs/environment/custom-domains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,31 +47,9 @@ After waiting for the DNS change to propagate (sometimes up to several hours) yo

## Custom domains for static files on S3

Some applications serve static files hosted on AWS S3. You can read the [Websites](/docs/websites.md#hosting-static-files-with-s3) documentation to learn more.
Some applications serve static files hosted on AWS S3. You can read the [Websites](/docs/websites.md) documentation to learn more.

The S3 bucket can be accessed at this URL: `https://<bucket>.s3.amazonaws.com/` (supports both HTTP and HTTPS).
If you want to host a fully static website with HTML files or a Single Page Application (eg. built with Vue, React or Angular)
you may be interested in [the Static Website construct of the Lift plugin](https://github.com/getlift/lift/blob/master/docs/static-website.md).

To use a custom domain for a S3 static website the process lies in 2 steps:

- name the S3 bucket like the wanted domain name

For example for the http://www.example.com website, the S3 bucket has to be named `www.example.com`
- point the domain to the S3 URL via DNS

In our example the DNS entry to create would be a CNAME for `www.example.com` pointing to `www.example.com.s3.amazonaws.com`

### Static websites

If you are hosting a full static website with HTML files ([per this documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html)), the URLs to use will be different:

```bash
http://<bucket>.s3-website-<region>.amazonaws.com/
# or
http://<bucket>.s3-website.<region>.amazonaws.com/
```

In that case you need to use the domains above for the CNAME.

Note that the URL is **HTTP-only** and [depends on the region](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_website_region_endpoints).

To add HTTPS to your website for free it is possible to use a CDN like [CloudFlare](https://cloudflare.com/) (simplest) or [AWS CloudFront](/docs/websites.md#serving-php-and-static-files-via-cloudfront).
This allows to configure custom domains, root domain to `www` redirects and more. Check out [the official documentation](https://github.com/getlift/lift/blob/master/docs/static-website.md) for more details.
52 changes: 45 additions & 7 deletions docs/frameworks/laravel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,21 +88,59 @@ For more details follow [the "Console" guide](/docs/runtimes/console.md).

## Assets

To deploy Laravel websites, we need assets to be served by AWS S3. Setting up the S3 bucket is already explained in the [websites documentation](../websites.md#hosting-static-files-with-s3). This section provides additional instructions specific to Laravel Mix.
To deploy Laravel websites, assets need to be served from AWS S3. The easiest solution to do this is to use the
[Server-side website construct of the Lift plugin](https://github.com/getlift/lift/blob/master/docs/server-side-website.md).
t-richard marked this conversation as resolved.
Show resolved Hide resolved

First, you can compile assets for production in the `public` directory, then synchronize that directory to a S3 bucket:
This will deploy a Cloudfront distribution that will act as a proxy: it will serve
static files directly from S3 and will forward everything else to Lambda. This is very close
to how traditional web servers like Apache or Nginx work, which means your application doesn't need to change!
For more details, see [the offical documentation](https://github.com/getlift/lift/blob/master/docs/server-side-website.md#how-it-works).

First install the plugin

```bash
npm run prod
aws s3 sync public/ s3://<bucket-name>/ --delete --exclude index.php
serverless plugin install -n serverless-lift
```

Then, the assets need to be included from S3. In the production `.env` file you can now set that variable:
Then add this configuration to your `serverless.yml` file.

```dotenv
MIX_ASSET_URL=https://<bucket-name>.s3.<region>.amazonaws.com
```yaml
...
service: laravel

provider:
...

plugins:
- ./vendor/bref/bref
- serverless-lift

functions:
...

constructs:
website:
type: server-side-website
assets:
'/js/*': public/js
'/css/*': public/css
'/favicon.ico': public/favicon.ico
'/robots.txt': public/robots.txt
# add here any file or directory that needs to be served from S3
Comment on lines +125 to +129
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is how it works in Laravel but I'm really not sure as I'm not using it. Would be helpful if someone could confirm this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@GrahamCampbell maybe you can confirm whether those paths look correct? 🙏

This should be the list of static assets in a brand new/standard Laravel app. These static assets would be served by CloudFront + S3.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the manifest.json file from the public folder will need to be shipped in the lambda image for this to work

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unfortunately, that path can be changed in php land. will either be located at public/mix-manifest.json or public/{artbirarypath}mix-manifest.json

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For arbitrary path it makes sense that users that know how to customize it will know to also reflect such customization here

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I agree with Marco.

Said differently, we're looking for the "out of the box" config laravel mix provides.

But if the manifest needs to be included on the Lambda deployment package, we might want to state it in this doc or add it to the package.patterns config provided by the Laravel bridge.

We went with the second one in the Symfony Bridge.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All good then, because public/mix-manifest.json is not excluded from the Lambda deployment by default: https://github.com/brefphp/laravel-bridge/blob/master/config/serverless.yml#L15-L19

So it seems we are all good to merge here.

Thanks for the feedback both of you!

```

Before deploying, compile your assets using Laravel Mix.

```bash
npm run prod
```

Now deploy your website using `serverless deploy`. Lift will create all required resources and take care of
uploading your assets to S3 automatically.

For more details, see the [Websites section](/docs/websites.md) of this documentation
and the official [Lift documentation](https://github.com/getlift/lift/blob/master/docs/server-side-website.md).

### Assets in templates

Assets referenced in templates should be via the `asset()` helper:
Expand Down
3 changes: 3 additions & 0 deletions docs/frameworks/symfony.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,9 @@ upload all specified files and directories to the bucket.

> If you are not using Flex, update the `serverless.yml` file to exclude assets from the deployment ([see the recipe](https://github.com/symfony/recipes-contrib/blob/master/bref/symfony-bridge/0.1/serverless.yaml#L35))

For more details, see the [Websites section](/docs/websites.md) of this documentation
and the official [Lift documentation](https://github.com/getlift/lift/blob/master/docs/server-side-website.md).

### Assets in templates

For the above configuration to work, assets must be referenced in templates via the `asset()` helper as [recommended by Symfony](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets):
Expand Down
Loading