{"id":13841558,"url":"https://github.com/tobilg/aws-fullstack-website","last_synced_at":"2025-10-14T10:30:29.799Z","repository":{"id":86825557,"uuid":"222129170","full_name":"tobilg/aws-fullstack-website","owner":"tobilg","description":"Deploy your fullstack websites without all the hassle on AWS with CloudFront, S3, ACM, Route53, API Gateway and Lambda via Serverless.","archived":false,"fork":false,"pushed_at":"2019-11-22T05:44:21.000Z","size":102,"stargazers_count":141,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-07T04:23:45.124Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobilg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-11-16T16:41:30.000Z","updated_at":"2025-04-07T01:41:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"a7a2f460-0f18-48d8-8b31-ae51eb949cbc","html_url":"https://github.com/tobilg/aws-fullstack-website","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tobilg/aws-fullstack-website","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Faws-fullstack-website","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Faws-fullstack-website/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Faws-fullstack-website/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Faws-fullstack-website/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobilg","download_url":"https://codeload.github.com/tobilg/aws-fullstack-website/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Faws-fullstack-website/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018780,"owners_count":26086452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T17:01:14.872Z","updated_at":"2025-10-14T10:30:29.447Z","avatar_url":"https://github.com/tobilg.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","JavaScript (485)"],"sub_categories":[],"readme":"# aws-fullstack-website\nDeploy your fullstack websites without all the hassle on AWS with CloudFront, S3, ACM, Route53, API Gateway and Lambda via Serverless.\n\nAll set up via one [Serverless](https://www.serverless.com) command and minimum manual configuration!\n\n## Architecture\n\n![Serverless fullstack website on AWS](docs/architecture.png)\n\n### What is provisioned in your AWS account?\n* A S3 bucket containing your static website\n* A CloudFront distribution for global hosting of your static website via CDN\n* An API Gateway endpoint for the API backend Lambda function\n* A Lambda function for the API backend\n* A HostedZone on Route53 with A records for your domain name\n* A Lambda function for automatic SSL certificate generation via ACM for your domain name (run once upon deployment)\n* DNS records for your custom domain (with `www.` and `api.` subdomains)\n\nAll of the CloudFormation resources reside in the `resources` subfolder.\n\n## Preconditions\nThis guide assumes that you have a pre-existing domain which you want to use for hosting your static website. Furthermore, you need to have access to the domain's DNS configuration.\n\nAlso, you need to have an install of [Serverless](https://www.serverless.com) on your machine.\n\n## How-to\nTo use this blueprint with your own static websites, you can follow the steps below to get started.\n\n### Set up a Serverless project for your static website\nThere are basically two ways to get started, either use [Serverless](https://www.serverless.com) to generate a basic project structure, or use the \"traditional\" fork and clone mechanisms.\n\n#### Use Serverless templates\nThe following command will create a local project structure you can use to deploy your static website in the `myfullstackwebsite` folder relative to your current working directory:\n\n```bash\n$ sls create --template-url https://github.com/tobilg/aws-fullstack-website --path myfullstackwebsite\nServerless: Generating boilerplate...\nServerless: Downloading and installing \"aws-fullstack-website\"...\nServerless: Successfully installed \"aws-fullstack-website\"\n```\n\n**Hint**  \nWhen using this method, Serverless is replacing the `service.name` in the `serverless.yml` file automatically with `myfullstackwebsite`. If you want to use a different stack name, you have to replace it manually. You also need to take care of that the stack name is using only allowed characters. When using the \"Fork and clone\" method below, the stack name is automatically derived from the domain name and sanitized regarding the allowed characters.\n\n#### Fork and clone\nOnce you forked the repo on GitHub, you can clone it locally via\n\n```bash\n$ git clone git@github.com:youraccount/yourrepo.git\n```\n\nwhere `youraccount/yourrepo` needs to be replaced with the actual repository name of your forked repo.\n\n### Install dependencies\nTo install the dependencies, do a \n\n```bash\n$ npm i\n```\n\nAfter that, the project is usable.\n\n### Create your static website\nYou can now create your static website in the `website` folder of your cloned repo.\n\n### Create your API backend\nThe API backend files can be found in the `api` subfolder. There are some default files which yoou can leave unchanged, the actual API lives in the `api/routes/v1/api.js` file.\n\nIt uses the [Lambda API package](https://www.npmjs.com/package/lambda-api), which provides an intuitive way to write API routes and has a lot of built-in functionalities. If you're familiar with writing APIs with [Express](https://www.npmjs.com/package/express), you should be able to come up to speed quite quickly.\n\n#### Base routes\nThe following routes do pre-exist:\n\n```text\nGET /favicon.ico    Returns the static favicon.ico from the 'api/static' folder\nGET /v1/info        Returns the API version information \n                    (derived from the 'package.json' file)\nGET /v1/api-docs    Returns the OpenAPI v3 documentation of the API\n```\n\n#### API docs\nJust point [editor.swagger.io](https://editor.swagger.io/) with `File -\u003e Import URL` to `https://api.yourdomain.yourtld/v1/api-docs` where `yourdomain.yourtld` is the domain name you specified as `--domain` argument while deploying. Once you finished editing, just copy and paste the Swagger Editor contents to the `api/static/api-docs.yml` file. After a new deployment, your API docs will be updated.\n\n### Additional AWS resources\nIf you want to add additional AWS resources, such as a DynamoDB table, you can do this by creating a new file in the `resources` folder, and then use it in the `serverless.yml` file's `resources` section like this:\n\n```yaml\nresources:\n  - ${file(resources/my-new-resource.yml)}\n```\n\n#### Example\nAn example on how to add a DynamoDB table might look like this: Create a new file `resources/dynamodb-table.yml` with the following content:\n\n```yaml\nResources: \n  BaseDataTable: \n    Type: AWS::DynamoDB::Table\n    Properties: \n      TableName: 'my-table'\n      KeySchema: \n        - \n          AttributeName: 'partitionKey'\n          KeyType: 'HASH'\n        - \n          AttributeName: 'sortKey'\n          KeyType: 'RANGE'\n      AttributeDefinitions: \n        - \n          AttributeName: 'partitionKey'\n          AttributeType: 'S'\n        - \n          AttributeName: 'sortKey'\n          AttributeType: 'S'\n      BillingMode: PAY_PER_REQUEST\n```\n\nThen, add the following line to the `resources` section of the `serverless.yml` file:\n\n```yaml\nresources:\n  # other resources\n  - ${file(resources/dynamodb-table.yml)}\n  # other resources\n```\n\nAfter that, you can (re-)deploy your fullstack wesite (see below).\n\n### Deploy\nYou can deploy your static website with the following command:\n\n```bash\n$ sls deploy --domain yourdomain.yourtld\n```\n\nwhere `yourdomain.yourtld` needs to be replaced with your actual domain name. You can also specify a AWS region via the `--region` flag, otherwise `us-east-1` will be used.\n\n#### Manual update of DNS records on first deploy\nOn the first deploy, it is necessary to update the DNS setting for the domain manually, otherwise the hosted zone will not be able to be established.\n\nTherefore, once you triggered the `sls deploy` command, you need to log into the AWS console, go to the [Hosted Zones](https://console.aws.amazon.com/route53/home?region=us-east-1#hosted-zones:) menu and select the corresponding domain name you used for the deployment.\n\nThe nameservers you have to configure your domain DNS to can be found under the `NS` record and will look similar to this:\n\n```bash\nns-1807.awsdns-33.co.uk.\nns-977.awsdns-58.net.\nns-1351.awsdns-40.org.\nns-32.awsdns-04.com.\n```\n\nYou should then update your DNS settings for your domain with those values, **otherwise the stack creation process will fail**.\n\nThis is a bit misfortunate, but to the best of knowledge there's currently no other way possible if you use AWS external (non-Route53) domains. During my tests with [namecheap.com](https://www.namecheap.com) domains the DNS records were always updated fast enough, so that the stack creation didn't fail.\n\n#### Deployment process duration\nAs a new CloudFront distribution is created (which is pretty slow), it can take **up to 45min** for the initial deploy to finish. This is normal and expected behavior.\n\n### Post-deploy\nIf the deployment finished successfully, you will be able to access your domain via `https://www.yourdomain.yourtld` and `https://yourdomain.yourtld`.\n\n### Updates\nFor every update of your website, you can trigger a deploy as stated above. This will effectively just do s S3 sync of the `website` folder. \n\nTo do a manual sync, your can also use `sls s3sync`. There's also the possibility to customize the caching behavior for individual files or file types via the `serverless.yml`, see the [s3sync plugin's documentation](https://www.npmjs.com/package/serverless-s3-sync#setup).\n\nAs **CloudFront caches the contents of the website**, a [Serverless plugin](https://github.com/aghadiry/serverless-cloudfront-invalidate) is used to invalidate files. This [may incur costs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html#PayingForInvalidation), see the [docs](https://aws.amazon.com/de/premiumsupport/knowledge-center/cloudfront-serving-outdated-content-s3/) for more info. \n\nYou can run `sls cloudfrontInvalidate` to do a standalone invalidation of the defined files in the `serverless.yml`.\n\n## Removal\nIf you want to remove the created stack, your will have to delete all records of the Hosted Zone of the respective domain except the `SOA` and `NS` records, otherwise the stack deletion via\n\n```bash\n$ sls remove --domain yourdomain.yourtld\n```\n\nwill fail.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Faws-fullstack-website","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobilg%2Faws-fullstack-website","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Faws-fullstack-website/lists"}