[RFC] Server-side Website

[mnapoli]

The goal of this discussion is to get feedback on a "Server-side Website" component.

By Server-side website, I mean a website where the HTML is rendered on the server. This is usually done with backend frameworks like Laravel/Symfony (PHP), Ruby on Rails, Django/Flask (Python), Express (Node), etc.

To build a SPA or static website, use the Static Website construct instead.

Name

Possible names for the constructs could be:

• server-side website
• server website
• dynamic website
• backend website

Any opinion? IMO "server-side" (or "server") goes nicely with "static website".

Use case

Deploying websites served via code on Lambda. E.g. websites built with Laravel/Symfony (PHP with Bref), Django/Flask (Python with the wsgi plugin), Express/... (Node), etc.

Quick start

# serverless.yml
# [...]

functions:
    home:
        handler: home.handler
        events:
            -   httpApi: 'GET /'
    # ...

constructs:
    website:
        type: server-side-website
        assets:
            '/css/*': dist/css
            '/js/*': dist/js

The example above will set up CloudFront to serve both:

• https://<domain>/* -> the website through API Gateway + Lambda
• https://<domain>/css/* and https://<domain>/js/* ->assets through S3

On serverless deploy, assets are uploaded to S3 and the CloudFront cache is invalidated.

Note: this component takes about 5 minutes to deploy the first time.

How it works

Why CloudFront?

API Gateway's HTTP APIs do not support HTTP. For a website, this is problematic because it means someone typing website.com in a browser will get a blank page: API Gateway will not even redirect this to HTTPS.

We need CloudFront to redirect HTTP -> HTTPS.

CloudFront also provides caching of assets (just like for static websites, as well as routing URLs based on prefixes:

• assets will be served by S3
• all other pages will be served by API Gateway

CloudFront configuration

CloudFront is configured to cache static assets by default, but not cache dynamic content by default.

CloudFront is configured to forward all headers, cookies, and query strings to the backend running on Lambda.

Using CloudFront Functions, the X-Forwarded-Host header will also be automatically populated to resolve a shortcoming of CloudFront + API Gateway. Code running on Lambda will be able to access the original Host header via this X-Forwarded-Host header.

Commands

serverless deploy deploys everything configured in serverless.yml and uploads assets.

It is possible to skip the CloudFormation deployment and directly publish assets changes via:

serverless <construct-name>:assets:upload

# For example:
serverless website:assets:upload

This command only takes seconds: it directly uploads files to S3 and clears the CloudFront cache.

Configuration reference

API Gateway

functions:
    v1:
        handler: foo.handler
        events:
            -   http: 'GET /' # REST API
    v2:
        handler: bar.handler
        events:
            -   httpApi: 'GET /' # HTTP API

constructs:
    website:
        type: server-side-website
        apiGateway: "http" # or "rest"

• if severless.yml only deploys a API Gateway v1 REST API, then the construct should use it
• if severless.yml only deploys a API Gateway v2 HTTP API, then the construct should use it
• if severless.yml deploys both a REST API and an HTTP API, then the user should configure which one to use:

If there is no Lambda function configured to respond to HTTP requests then the construct should show an error to the user (an API Gateway is required).

Assets

constructs:
    website:
        # ...
        assets:
            '/assets/*': dist/

The assets section lets users define routing for static assets (like JavaScript, CSS, images, etc.).

• The key defines the URL pattern.
• The value defines the local path to upload.

Assets can be either whole directories, or single files:

constructs:
    website:
        # ...
        assets:
            # Directories: routes must end with `/*`
            '/css/*': dist/css
            '/images/*': assets/animations
            # Files:
            '/favicon.ico': public/favicon.ico

With the example above:

• https://<domain>/* -> Lambda
• https://<domain>/css/* -> serves the files uploaded from the local dist/css directory
• https://<domain>/images/* -> serves the files uploaded from the local assets/animations directory
• https://<domain>/favicon.ico -> serves the file uploaded from public/favicon.ico

Custom domain

constructs:
    website:
        # ...
        domain: mywebsite.com
        # ARN of an ACM certificate for the domain, registered in us-east-1
        certificate: arn:aws:acm:us-east-1:123456615250:certificate/0a28e63d-d3a9-4578-9f8b-14347bfe8123

This will behave similarly to the static website domain configuration.

Error pages

constructs:
    website:
        # ...
        errorPage: error500.html

In case a web page throws an error, API Gateway's default Internal Error blank page shows up. This can be overridden by providing an HTML error page.

Applications are of course free to catch errors and display custom error pages. However, sometimes even error pages and frameworks fail completely: this is where the API Gateway error page shows up.

Draft pull request

A pull request with a draft implementation is available here: #44

[t-richard]

First, this is HUGE ! This is a major hassle for classic fullstack websites when running in Lambda.

Possible names for the constructs could be:
server-side website
server website
dynamic website
backend website

I would go with the 5th option : Fullstack Website 😅
Backend website could do the trick too I think.

What I dislike about Server-side website is that it could be misleading users to think this is a component to do Server-Side Rendering with their favorite frontend framework, especially in the JS community I suppose. (By the way, a construct to support this kind of SSR could be great too).

CloudFront is configured to cache static assets by default, but not cache dynamic content by default.

Is it Cloudfront edge cache where an invalidation will clear everything up, or is it a cache-control header added to the assets ?

If it's the later, would it be possible to configure which paths are cached and which are not ?

If using something like webpack, you can add a hash to assets but if your are building something simple, then you wmight not version your assets and some third parties might not allow that at all (for example, Symfony assets provided by third-party bundles are not versionned and I'm not sure you can do it).

Something like

constructs:
    website:
        # ...
        assets:
            '/bundles/*': 
                   path: public/bundles/
                   cache: false # this disables cache-control headers or sets it to 0
            '/build/*': public/build/ # this uses the default cache behaviour

Let me know what you think.

[t-richard]

🤯 omg this is crazy. Why! 😄

Was also shoked when I discovered it. When a site is not updated on a regular basis, browsers could keep some files in cache for days or weeks.

And on the naming again, I think my "Server-Side Rendering could be confusing" point doesn't stand actually. Because I think this construct could also be used on these.

The basis when doing SSR on Lambda is that assets are redirected to S3 by Cloudfront and everything else is passed to a Lambda in charge of the Server-Side Rendering (with Nuxt, Next, etc). So the current approach could work for those too. I guess.

[mnapoli]

If no cache-control header is set, browsers will fallback to a cache duration of 10% the time elapsed since Last-Modified header (which would the upload to S3 date in our case).

@t-richard I'm wrapping up the server-side website, I'm wondering about that: I'm thinking about adding systematically a cache-control header that says "don't cache" (so that browsers will never cache the files). But then CloudFront will also not cache them, right?

Note that for now I want to stick to a simple strategy:

• cache in cloudfront
• no browser cache

This is so that it works out of the box. Then we can iterate later on browser caching with more options.

[t-richard]

You can control the minimum TTL of Cloudfront cache that will take over the cache-control if max-age=0.

In our case we could have Cache-Control: max-age=0 set on S3 objects and set a Minimum Cache TTL of a given value (24h, 7 days, or more). This way browsers would not cache the file but Cloudfront would use the minimum TTL as a default value for edge caching.

See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html#ExpirationDownloadDist

It would just mean you'll have to create a custom cache policy to replace CachePolicy.CACHING_OPTIMIZED because it sets the Min TTL to 1s

[mnapoli]

So… I'm investigating that again, and I'm questioning the whole thing: I don't see a Last-Modified header with CloudFront:

So maybe we don't have that problem at all here? Was there a specific reason you thought about that header here? I'm afraid of missing something, especially since it's been a while 😅

[mnapoli]

Just tested again a real scenario: deployed a CSS file yesterday. I opened the website in my browser and navigated: the CSS was loaded at first and then CloudFront returned 304 (Not Modified).

This morning, I opened the website and navigated it (still 304). Then I uploaded CSS changes (Lift did the CloudFront invalidation). I did not "refresh" the page, simply clicked a link to go to a new page: the new CSS was loaded.

From what I can tell we don't have an issue here.

[t-richard]

tested it yesterday with symfony/demo and it worked for the most part.

There are still some hiccups which are blocking it even on a simple app like the demo :

• X-Forwarded-Host is not set so redirects are generated using API Gateway's endpoint (because it's in the Host header). It would be nice to set it when the user provides a domain.
• Some headers are whitelisted but you could easily run into cases where more headers are needed (in the case of the demo, it uses X-Requested-With to determine if the request is a XHR. Other headers like X-Api-Key or CORS related headers. Some custom headers might be needed too so I think it's important to allow configuration of the headers.

Otherwise, it seems to work well. I'll to test this with a Server-Side rendered Vue app I have and see how it turns out.

[t-richard]

What do you have in mind with OriginCustomHeaders? What do you mean by that?

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudfront-distribution-origin.html#cfn-cloudfront-distribution-origin-origincustomheaders

You can add fixed headers in the cloudformation and add the user provided domain there (I think this is what is outlined in the assets docs of bref for the x-forwarded-header)

Yeah you're making a good point: a server-side website can implement any redirect it wants… Including the www one actually

I think it makes sense for advanced redirects but www redirects would be great to have by default. It would feel wrong to implement this in the server code IMHO.

[mnapoli]

🤦 oh ok I see what you meant now. Yeah hardcoding the header works if you only host your app on a single domain. If you support multiple domains, then you are out of luck. I was thinking of solving this once and for all with CloudFront Functions.

The security aspect is a good point but AFAICT CloudFront will not serve your app on an invalid header (I should test that to be sure), so that shouldn't be an issue here.

[t-richard]

The security aspect is a good point but AFAICT CloudFront will not serve your app on an invalid header (I should test that to be sure), so that shouldn't be an issue here.

I tested it and it is apparently not possible to "poison" the Host header with Cloudfront. This was also stated in some articles like this one which says

If the HOST header does not match a domain in the “Alternate Domain Names (CNAMEs)” field of the intended distribution, the request will fail.

And the rest of the article is not of interest to us I think even if it's a quite interesting read 🤓

If you support multiple domains, then you are out of luck

True, so Cloudfront functions are the way out of this. The pricing and overhead are so low that it seems like the best solution.

[mnapoli]

Quick update following some attempts:

• when a single custom domain is set, we can use OriginCustomHeaders
• when multiple custom domains are set, we cannot use OriginCustomHeaders, we must use CFF
• when no custom domains are set, we cannot put the CloudFront domain in OriginCustomHeaders because we cannot do a CloudFormation reference to itself…

All that leads me to think that deploying CFF all the time is a simpler solution.

For reference, here is a possible solution for actually having the correct Host header: https://stackoverflow.com/a/53343079/245552 But since this isn't documented, and this is quite a hassle to set up, I don't want to go that route. I think having X-Forwarded-Host is acceptable.

[t-richard]

I think it makes sense to do it consistently with CFF. It will be easier to implement, explain and maintain.

[mykiwi]

Quick question, how can I test it on a project? It is not merged yet, so I'm not sure what should I do to install this package version.

[t-richard]

I think your node version is too high
See

lift/package.json

Line 66 in 5ad131b

"node": ">=10 <16"

Could you try with node ^15.14 ?

[mykiwi]

I will try, but what I don't understand is that it is working correctly with the main version and this requirement is the same 🤔

[t-richard]

When you install from a branch, npm will run the "prepare" script so you need development requirements to run this so that's why it is different than installing a published version which is already built.

Basically npm will clone the repo in a tmp dir, install dependencies (including dev), run the prepare script which will build the project then copy that in node_modules of the project you are trying to install it into. It's because of the build phase that you need different versions.

[mykiwi]

This works! Thank you 😃

[mnapoli]

@mykiwi sorry, holidays here :)

Happy to see some interest in this, let me know if you have any feedback on the construct.

[mykiwi]

Thank you for this! This works great.

But how can we correctly handle different stages?
For example when I try to deploy my site with serverless deploy --stage=foo this does not works. Here is the output:

 Serverless Error ----------------------------------------
 
  An error occurred: websiteCDN012346 - Resource handler returned message: "Invalid request provided: One or more of the CNAMEs you provided are already associated with a different resource. (Service: CloudFront, Status Code: 409, Request ID: abcdef, Extended Request ID: null)" (RequestToken: ghijklm, HandlerErrorCode: InvalidRequest).
 
  Get Support --------------------------------------------
     Docs:          docs.serverless.com
     Bugs:          github.com/serverless/serverless/issues
     Issues:        forum.serverless.com
 
  Your Environment Information ---------------------------
     Operating System:          linux
     Node Version:              15.14.0
     Framework Version:         2.52.1
     Plugin Version:            5.4.3
     SDK Version:               4.2.5
     Components Version:        3.14.0

It could be nice to allow a main stage = main domain (my.domain.com) & custom stage = a (customizable?) pattern like {stage}.my.domain.com or another cloudfront url.

[t-richard]

You are able to combine Lift constructs with Serverless framework variables. Something like this should do the trick

...

custom:
  domain:
    prod: my.domain.com
    other: ${sls:stage}.my.domain.com

constructs:
    website:
        type: server-side-website
        domain: ${self:custom.domain.${sls:stage}, self:custom.domain.other}
        assets:
            '/css/*': dist/css
            '/js/*': dist/js

This way, serverless deploy --stage=prod would use my.domain.com and all others would use {stage}.my.domain.com

You could also use an env variable if you deploy via CI/CD

IMHO, this is out of the scope of Lift because Serverless Framework allows for a lot of flexibility already.

[mnapoli]

👍 one solution is to have something like:

constructs:
    website:
        # ...
        domain: ${sls:stage}.mywebsite.com

but it wouldn't really work for prod (prod.mywebsite.com instead of mywebsite.com).

Or you could end up with something complex like:

custom:
    domains:
        prod: mywebsite.com
        staging: staging.mywebsite.com

constructs:
    website:
        # ...
        domain: ${self:custom.domains.${sls:stage}}

I'm not sure if there's any native feature we could include in this construct specifically (what would it look like?). After all, the same problem probably applies to all constructs.

Maybe another approach would be something more generic, like:

constructs:
    website:
        if: stage == 'prod'
        # ...
        domain: mywebsite.com

    website-dev:
        if:  stage !== 'prod'
        # ...
        domain: ${sls:stage}.mywebsite.com

This kind of logic could apply to all constructs.

[mykiwi]

Thanks for the answers! I will try it 😃

[mnapoli]

Hey all, a quick update. I've been reading about HSTS (which is nothing new) and TIL: there are now lists maintained by Chrome and Firefox of "HTTPS-only" websites (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security#preloading_strict_transport_security).

That allows a website to be 100% HTTPS-only, and still work in all browsers.

That makes me think that we may want to consider hosting websites without CloudFront at all? CloudFront is still useful to host everything behind a single domain and benefit from CDN caching. But it takes a while to setup/deploy.

Maybe we will want a simple-website construct? I'm just throwing the idea out there. CloudFront may not be absolutely required anymore.

[piolet]

a website with a 100% server rendering?
But then, where would the assets be if there is no more CDN?

[mnapoli]

Served directly from S3

[piolet]

Hum, ok... With static web host option activated ?

But S3 don't manage https, that's not a problem?

[mnapoli]

No that would be without static website hosting (so HTTPS is supported). Static websites would not be supported (since this is a server-side website construct). 100% server rendering.

[piolet]

ok ok.

Not yet my use case, but ok. It make sense

[jjmontgo]

How would I handle a case where I want to provide public access to user uploaded files? Is there any way to map a path, /uploads, to a storage S3 bucket?

[mnapoli]

The bucket created in the server-side-website construct is for storing assets. Not for user-uploaded files.

I encourage you to create a separate bucket for the uploaded files.

[jjmontgo]

That's the strategy I've taken -- with a separate bucket and a separate cloudfront distribution for accessing a public folder in the bucket. It would have been nice if I could have added an additional backend to the distribution created by the plugin, but you can't have it all. Thank you!

[hmazter]

Would it be possible to create a new version of this construct or update this to use the Lambda Function Url instead of API Gateway?

Lambda Function Url seems like the perfect companion for this construct together with something like Laravel

[mnapoli]

@hmazter we could indeed, but I wonder if adding another option like this one https://github.com/getlift/lift/blob/master/docs/server-side-website.md#api-gateway would make sense? It would be much simpler. For example:

constructs:
    website:
        type: server-side-website
        lambdaUrl: function-name

WDYT?

[hmazter]

It works for me 👍
Just did not want to suggest increased underlying complexity 😄

[mnapoli]

I think for this case specifically it's OK

[AtteR]

Hello,

With the new extensions, is it possible to add new origins for website construct? I have tested this:

`website:

extensions:

  distribution:

    Properties:

      DistributionConfig:

        Origins:

          - DomainName: ${construct:contents.bucketName}.s3.{$aws:region}.amazonaws.com
          
            Id: ContentsOrigin

            S3OriginConfig:

              OriginAccessIdentity: !Join ['', ['origin-access-identity/cloudfront/', !Ref CloudFrontContentsAi]]

`

Getting this error:

Invalid request provided: One or more of your origins or origin groups do not exist

Is my .yml simply wrong or is there something I am missing? Looking to create Cloudfront distribution for user uploaded files. Do I need to create completely new distribution for this?

Thank you.

[mnapoli]

I don't think you can do that as it might override the Origins entirely?

[kevincerro]

I'm trying to do this also.

We want to add one origin and one behaviour to the cloudfront created by lift server-side-construct

Nowadays is possible to do this? @mnapoli

[mnapoli]

@kevincerro I don't think it's possible to do this easily, not sure where to point you except to create your own cloudformation template

[kevincerro]

@mnapoli Maybe this can be used
Our use case is to host under a subpath /blog/ a static-website construct / s3 bucket
#325