Creating serverless PHP websites
Before reading this article we assume that you have read Bref's introduction and that you are familiar with Bref's HTTP runtime.
Architectures
Websites usually contain 2 parts:
- PHP code, running on AWS Lambda + API Gateway with the HTTP runtime
- static assets (CSS, JS…), hosted on AWS S3
CloudFront (the AWS CDN) serves as an HTTP/HTTPS proxy.
This lets us host everything under the same domain and support both HTTP and HTTPS.
The easiest approach is to use the Server-side website construct of the Lift plugin. If you don't want to use it, see the alternative solutions.
First install the plugin
serverless plugin install -n serverless-lift
Then add this configuration to your serverless.yml
file.
service: my-app
provider:
...
plugins:
- ./vendor/bref/bref
- serverless-lift
functions:
...
constructs:
website:
type: server-side-website
assets:
'/js/*': assets/js
'/css/*': assets/css
'/favicon.ico': assets/favicon.ico
'/robots.txt': assets/robots.txt
# add here any file or directory that needs to be served from S3
Now deploy your website using serverless deploy
. Lift will create all required resources and take care of
uploading your assets to S3 automatically.
You can access your website using the URL that Lift outputs at the end the deployment.
The first deployment takes a lot of time (5 to 10 minutes) because CloudFront is a distributed service. The next deployments that do not modify CloudFront's configuration will not suffer from this delay.
Setting up a domain name
Just like in the "Custom domains" guide, you need to register your domain in ACM (AWS Certificate Manager) to get an HTTPS certificate.
If you have already set up this domain as a custom domain in API Gateway (by following the Custom domain guide), you will need to remove it before continuing.
- open this link or manually go in the ACM Console and click "Request a new certificate" in the
us-east-1
region (CloudFront requires certificates fromus-east-1
) - add your domain name and click "Next"
- choose the domain validation of your choice
- domain validation will require you to create DNS entries (this is recommended because it renews the certificate automatically)
- email validation will require you to click a link you will receive in an email sent to
admin@your-domain.com
Copy the ARN of the ACM certificate. It should look like this:
arn:aws:acm:us-east-1:216536346254:certificate/322f12ee-1165-4bfa-a41f-08c932a2935d
Now add your domain name and certificate in your serverless.yml
file
...
constructs:
website:
# ...
domain: mywebsite.com
certificate: <your certificate ARN>
The last step will be to point your domain name DNS records to the CloudFront URL:
- copy the domain outputted by Lift during
serverless deploy
(or runserverless info
to retrieve it) - create a CNAME to point your domain name to this URL
- if you use Route53 you can read the official guide
- if you use another registrar and you want to point your root domain (without
www.
) to CloudFront, you will need to use a registrar that supports this (for example CloudFlare allows this with a technique called CNAME flattening)
Lift supports more advanced use cases like multiple domains, root domain to www
redirects, and more. Check out the official documentation.
Alternative solutions
If you don't want to use Lift or Cloudfront, you may want to read the older version of this documentation which featured configuration using S3 only on a separate domain and Cloudfront configured through plain CloudFormation.