VK Cloud logo

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

Preparation steps

  1. Make sure that AWS CLI is installed and configured.

  2. 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.
  3. Install Node.js version 18 or higher, if not already installed.

  4. Create an Astro project:

    npm create astro@latest
  5. Make sure you have access to managing DNS records for the astro.example.com domain.

1. Build the Astro project

  1. Navigate to the Astro project directory.

  2. Make sure that static output is configured in the astro.config.mjs file:

    import { defineConfig } from 'astro/config';export default defineConfig({  output: 'static',});
  3. Build the project:

    npm run build

    The ./dist directory will contain the site's static files: index.html, error pages, images, CSS and JavaScript files.

  4. Make sure that the index.html and 404.html files are present in the root of ./dist. If the 404.html file was not created automatically, create it manually.

2. Configure the bucket for static site hosting

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

3. Configure access permissions and CORS

  1. Configure public read access for the site objects. Use one of the following methods.

    1. Create a policy.json file 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/*"]   }]}
    2. 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
  2. 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.

4. Upload the site files to the bucket

  1. Synchronize the contents of the ./dist directory with the bucket using AWS CLI:

    aws s3 sync ./dist s3://astro-site-bucket \  --endpoint-url https://hb.ru-msk.vkcloud-storage.ru

    The command uploads only new and modified files, which speeds up repeated deployments.

  2. Make sure the files are uploaded:

    aws s3 ls s3://astro-site-bucket \  --endpoint-url https://hb.ru-msk.vkcloud-storage.ru

5. Connect the CDN and bind the domain

  1. Create a CDN resource via the interface of the astro-site-bucket bucket. Specify the following parameters:

    • Custom domain: astro.example.com.
    • Cache lifetime: 4. For a static site, a value from 1 to 7 days is recommended.
  2. Click Go to CDN resource to open the CDN section for further configuration.

  3. 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.

  4. Enable content access for end users. This is necessary so that you can then select Let's Encrypt as the SSL certificate.

  5. 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.

  6. 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.

  7. Configure the DNS record: create a CNAME record for the astro.example.com domain, 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.

6. Configure caching rules

Configure caching for the CDN resource. For more information about recommended TTL values for different content types, see the Content caching section.

7. Configure access to your content

  1. Configure a domain access policy to prevent other sites from using your resources.
  2. Configure a country access policy for your origins to restrict content access based on geography.

8. Verify the setup

  1. Open the site at https://astro.example.com in a browser. The main page of the Astro site should be displayed.

  2. Check the error page — open a non-existent URL, for example https://astro.example.com/nonexistent-page. The 404.html page should be displayed.

  3. Check the response headers:

    curl -I https://astro.example.com

    Make sure that:

    • The Content-Type header specifies the correct MIME type.
    • Caching headers from the CDN are present.
  4. Check that images and other static resources load correctly.

Delete unused resources

The created resources are billed. If you no longer need them:

  1. Delete the objects from the bucket.
  2. Delete the bucket.
  3. Delete the CDN resource, if it is no longer needed.
Was this article helpful?