diff --git a/public/images/aws/s3-static-website-terraform-diagram.png b/public/images/aws/s3-static-website-terraform-diagram.png new file mode 100644 index 00000000..854c7be2 Binary files /dev/null and b/public/images/aws/s3-static-website-terraform-diagram.png differ diff --git a/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx b/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx index 25800509..9ad33a65 100644 --- a/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx +++ b/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx @@ -12,14 +12,13 @@ pro: false leadimage: "s3-static-website-terraform-featured-image.png" --- +## Introduction + [AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is a proprietary object storage solution that can store an unlimited number of objects for many use cases. -S3 is a highly scalable, durable and reliable service that we can use for various use cases: hosting a static site, handling big data analytics, managing application logs, storing web assets and much more! +S3 is a highly scalable, durable and reliable service that we can use for any use case involving file-based storage: hosting a static site, handling big data analytics, managing application logs, storing web assets and much more! -With S3, you have unlimited storage with your data stored in buckets. -A bucket refers to a directory, while an object is just another term for a file. -Every object (file) stores the name of the file (key), the contents (value), a version ID and the associated metadata. -You can also use S3 to host a static website, to serve static content. -It might include HTML, CSS, JavaScript, images, and other assets that make up your website. +With S3, objects are stored in buckets. A bucket is effectively a directory, while an object is a file. Every object (file) stores the name of the file (key), the contents (value), a version ID and the associated metadata. You can also use S3 to host to server static content as a static website. +The static content might include HTML, CSS, JavaScript, images, and other assets that make up your website. LocalStack supports the S3 API, which means you can use the same API calls to interact with S3 in LocalStack as you would with AWS. Using LocalStack, you can create and manage S3 buckets and objects locally, use AWS SDKs and third-party integrations to work with S3, and test your applications without making any significant alterations. @@ -37,6 +36,18 @@ For this tutorial, you will need: - [Terraform](https://www.terraform.io/downloads.html) - [awslocal](https://github.com/localstack/awscli-local) +## Architecture + +The following diagram illustrates the architecture of the static website hosting setup using S3 and Terraform: + +![Architecture](/images/aws/s3-static-website-terraform-diagram.png) + +In this architecture: +- A browser makes an HTTP request to the S3 website endpoint +- LocalStack's S3 service serves the static content from the configured bucket +- The bucket contains HTML files and optional assets +- Terraform provisions and configures all resources locally + ## Creating a static website We will create a simple static website using plain HTML to get started. @@ -374,6 +385,61 @@ tflocal plan tflocal apply ``` +## Testing the application + +After deploying your static website, it's important to verify that everything is working correctly. +Here are several ways to test your S3-hosted static website: + +### Accessing the website + +Navigate to the LocalStack S3 website endpoint in your browser: + +``` +http://testwebsite.s3-website.localhost.localstack.cloud:4566/ +``` + +You should see your `index.html` content displayed, which in our case shows: "Static Website deployed locally over S3 using LocalStack". + +### Testing with curl + +You can also test the website using `curl` from your terminal: + +```bash +curl http://testwebsite.s3-website.localhost.localstack.cloud:4566/ +``` + +This should return the HTML content of your `index.html` file. + +### Verifying the error page + +To test the custom error document, try accessing a non-existent page: + +```bash +curl http://testwebsite.s3-website.localhost.localstack.cloud:4566/nonexistent.html +``` + +You should receive the content from your `error.html` file: "Something is amiss." with an appropriate HTTP 4XX status code. + +### Checking bucket configuration + +You can verify the bucket's website configuration using `awslocal`: + +```bash +awslocal s3api get-bucket-website --bucket testwebsite +``` + +This command should return the index and error document configuration for your bucket. + +### Listing bucket contents + +To confirm all your files were uploaded correctly: + +```bash +awslocal s3 ls s3://testwebsite/ +``` + +This will display all the files in your bucket, including `index.html`, `error.html`, and any additional assets. + ## Conclusion In this tutorial, we have seen how to use LocalStack to create an S3 bucket and configure it to serve a static website.