Deploying an Astro site to object storage with CDN
Using VK Object Storage and CDN, you can deploy a static site built with the Astro framework, with global content delivery and low latency. Object storage acts as serverless hosting for the frontend, while the CDN provides caching on edge servers and content delivery over HTTPS.
The following data is used as an example:
- Bucket name:
astro-site-bucket - Site domain name:
astro.example.com - Directory of the built project:
./dist - Storage endpoint:
https://hb.ru-msk.vkcloud-storage.ru
-
Make sure that AWS CLI is installed and configured.
-
Create a bucket in VK Object Storage with the following parameters:
- Name:
astro-site-bucket. The bucket name must comply with the naming rules. - Storage class:
Hotbox— suitable for quickly serving a large number of files.
- Name:
-
Install Node.js version 18 or higher, if not already installed.
-
Create an Astro project:
npm create astro@latest -
Make sure you have access to managing DNS records for the
astro.example.comdomain.
-
Navigate to the Astro project directory.
-
Make sure that static output is configured in the
astro.config.mjsfile:import { defineConfig } from 'astro/config';export default defineConfig({output: 'static',}); -
Build the project:
npm run buildThe
./distdirectory will contain the site's static files:index.html, error pages, images, CSS and JavaScript files. -
Make sure that the
index.htmland404.htmlfiles are present in the root of./dist. If the404.htmlfile was not created automatically, create it manually.
Configure the static site configuration. In the configuration, specify the index document and the error page for the bucket. This can be done via a configuration file or directly in an AWS CLI command:
aws s3api put-bucket-website \--bucket astro-site-bucket \--website-configuration '{"IndexDocument":{"Suffix":"index.html"},"ErrorDocument":{"Key":"404.html"}}' \--endpoint-url https://hb.ru-msk.vkcloud-storage.ru
Here:
index.html— the document served when the bucket root is accessed.404.html— the document served when a 404 error occurs.
After configuring, the static site will be available at: https://astro-site-bucket.hb-website.hb.ru-msk.vkcloud-storage.ru
-
Configure public read access for the site objects. Use one of the following methods.
Access policy (recommended)ACL-
Create a
policy.jsonfile with a policy that allows anonymous reading of objects:{"Version": "2012-10-17","Statement": [{"Sid": "PublicReadGetObject","Effect": "Allow","Principal": "*","Action": "s3:GetObject","Resource": ["arn:aws:s3:::astro-site-bucket/*"]}]} -
Apply the policy:
aws s3api put-bucket-policy \--bucket astro-site-bucket \--policy file://policy.json \--endpoint-url https://hb.ru-msk.vkcloud-storage.ru
-
-
Configure CORS for the bucket if the site makes cross-domain requests to resources in the storage.
An example CORS XML configuration:
<CORSConfiguration><CORSRule><AllowedOrigin>https://astro.example.com</AllowedOrigin><AllowedMethod>GET</AllowedMethod><AllowedMethod>HEAD</AllowedMethod><AllowedHeader>*</AllowedHeader><MaxAgeSeconds>3000</MaxAgeSeconds></CORSRule></CORSConfiguration>Here:
AllowedOrigin— the site domain from which requests to the bucket are allowed.AllowedMethods— HTTP methods allowed in requests.MaxAgeSeconds— the time the results of a preflight request are cached in the browser.
-
Synchronize the contents of the
./distdirectory with the bucket using AWS CLI:aws s3 sync ./dist s3://astro-site-bucket \--endpoint-url https://hb.ru-msk.vkcloud-storage.ruThe command uploads only new and modified files, which speeds up repeated deployments.
-
Make sure the files are uploaded:
aws s3 ls s3://astro-site-bucket \--endpoint-url https://hb.ru-msk.vkcloud-storage.ru
-
Create a CDN resource via the interface of the
astro-site-bucketbucket. Specify the following parameters:- Custom domain:
astro.example.com. - Cache lifetime:
4. For a static site, a value from1to7days is recommended.
- Custom domain:
-
Click Go to CDN resource to open the CDN section for further configuration.
-
Save the service domain name of the CDN resource (for example,
cl-541e19d9.service.cdn.msk.vkcs.cloud) — you will need it to create a CNAME record. -
Enable content access for end users. This is necessary so that you can then select Let's Encrypt as the SSL certificate.
-
Select HTTPS as the origin communication protocol for the CDN resource to ensure secure data transfer to users. This is also required to use Let's Encrypt as the SSL certificate.
-
In the CDN resource encryption settings, select the Let's Encrypt option — a free SSL certificate will be used, which is created automatically after the CNAME records are propagated in DNS (usually up to 30 minutes). For more information on managing SSL certificates, see the Using an SSL certificate section.
-
Configure the DNS record: create a CNAME record for the
astro.example.comdomain, specifying the saved service domain name of the CDN resource as the alias. If you use the DNS service from VK Cloud, follow the instructions for adding DNS records.
Configure caching for the CDN resource. For more information about recommended TTL values for different content types, see the Content caching section.
- Configure a domain access policy to prevent other sites from using your resources.
- Configure a country access policy for your origins to restrict content access based on geography.
-
Open the site at
https://astro.example.comin a browser. The main page of the Astro site should be displayed. -
Check the error page — open a non-existent URL, for example
https://astro.example.com/nonexistent-page. The404.htmlpage should be displayed. -
Check the response headers:
curl -I https://astro.example.comMake sure that:
- The
Content-Typeheader specifies the correct MIME type. - Caching headers from the CDN are present.
- The
-
Check that images and other static resources load correctly.
The created resources are billed. If you no longer need them:
- Delete the objects from the bucket.
- Delete the bucket.
- Delete the CDN resource, if it is no longer needed.