Hosting a static Gatsby website in Yandex Object Storage
In this tutorial, you will learn how to host your static Gatsby
To create and host a static website in Object Storage:
- Prepare your cloud.
- Register a domain name.
- Create the website locally.
- Create and configure an Object Storage bucket.
- Upload your website to the bucket.
- Configure HTTPS access.
If you no longer need the resources you created, delete them.
Prepare your cloud
Sign up for Yandex Cloud and create a billing account:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_ACTIVE
status. If you do not have a billing account, create one.
If you have an active billing account, you can go to the cloud page
Learn more about clouds and folders.
Required paid resources
Infrastructure support costs include fees for storing data in Object Storage, data operations, and outbound traffic (see Object Storage pricing).
Register a domain name
-
In your domain registrar's account, register a domain name, e.g.,
gatsbytest.ru
. -
To get access to public zone domain names, delegate the domain. To do this, in your domain registrar's account, specify the DNS server addresses:
ns1.yandexcloud.net
andns2.yandexcloud.net
.Delegation does not take effect immediately. It usually takes up to 24 hours for the internet service providers to update records.
You can check the domain delegation using Whois or thedig
utility:dig +short NS gatsbytest.ru
Result:
ns2.yandexcloud.net ns1.yandexcloud.net
Create the website locally
For testing purposes, create a website on your local computer using a template from the Gatsby Starter Library
-
To create the website, run these commands:
npm install -g gatsby-cli gatsby new my-gatsby-project https://github.com/gatsbyjs/gatsby-starter-blog cd gatsby-starter-blog
-
Make sure the website has been created. To do this, run the following command:
gatsby develop
Wait for the command to run and check that the website is available at this address:
http://localhost:8000
Create and configure an Object Storage bucket
Create a bucket
To host your static website in the cloud, create a bucket:
- In the management console
, select the folder you want to create a bucket in. - Select Object Storage.
- Click Create bucket.
- On the bucket creation page:
- Specify the domain name you registered, e.g.,
gatsbytest.ru
, as the name of your bucket. - For testing purposes, specify the minimum bucket size.
- Select the Public access type for all operations.
- Click Create bucket.
- Specify the domain name you registered, e.g.,
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
-
Create a bucket in the default folder:
yc storage bucket create \ --name <bucket_name> \ --default-storage-class <storage_class> \ --max-size <maximum_bucket_size> \ --public-read \ --public-list \ --public-config-read
Where:
--name
: Bucket name. Specify the domain name you registered, e.g.,gatsbytest.ru
.--default-storage-class
: Storage class. Possible values:standard
: Standard storage.cold
: Cold storage.ice
: Ice storage.
--max-size
: Maximum bucket size, in bytes (0
for unlimited).--public-read
: Flag to enable public access to read bucket objects.--public-list
: Flag to enable public access to view the list of bucket objects.--public-config-read
: Flag to enable public access to read bucket settings.
If you do not have the AWS CLI yet, install and configure it.
In the terminal, run the command below by specifying the bucket name and the Object Storage endpoint:
aws --endpoint-url=https://storage.yandexcloud.net \
s3 mb s3://<bucket_name>
Where:
--name
: Bucket name. Specify the domain name you registered, e.g.,gatsbytest.ru
.
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
In the configuration file, describe the parameters of the resources you want to create:
terraform { required_providers { yandex = { source = "yandex-cloud/yandex" } } required_version = ">= 0.13" } provider "yandex" { token = "<IAM_or_OAuth_token>" cloud_id = "<cloud_ID>" folder_id = "<folder_ID>" zone = "ru-central1-a" } resource "yandex_iam_service_account" "sa" { name = "<service_account_name>" } // Assigning roles to a service account resource "yandex_resourcemanager_folder_iam_member" "sa-editor" { folder_id = "<folder_ID>" role = "storage.editor" member = "serviceAccount:${yandex_iam_service_account.sa.id}" } // Creating a static access key resource "yandex_iam_service_account_static_access_key" "sa-static-key" { service_account_id = yandex_iam_service_account.sa.id description = "static access key for object storage" } // Creating a bucket using a key resource "yandex_storage_bucket" "test" { access_key = yandex_iam_service_account_static_access_key.sa-static-key.access_key secret_key = yandex_iam_service_account_static_access_key.sa-static-key.secret_key bucket = "<bucket_name>" }
Where:
yandex_iam_service_account
: Description of the service account that will create and use a bucket:name
: Service account name
yandex_storage_bucket
: Secret descriptionbucket
: Bucket name. Specify the domain name you registered, e.g.,gatsbytest.ru
.
-
Make sure the configuration files are correct.
- In the command line, go to the folder where you created the configuration file.
- Run a check using this command:
terraform plan
If the configuration is described correctly, the terminal will display a list of created resources and their parameters. If the configuration contains any errors, Terraform will point them out.
-
Deploy cloud resources.
-
Run this command:
terraform apply
-
Confirm that you want to create the resources.
All the resources you need will then be created in the specified folder. You can check the new resources and their configuration using the management console
. -
To create a bucket, use the create REST API method for the Bucket resource, the BucketService/Create gRPC API call, or the create S3 API method.
Configure your bucket
To configure a bucket for static website hosting:
- In the management console
, go to the bucket you want to configure hosting for. - Go to the
Website tab. - Under Hosting:
- In the Home page field, specify the absolute path to the file of the website home page. For the website from the Gatsby template, specify
index.html
. - Optionally, in the Error page field, you can specify the absolute path to the file displayed on 4xx errors. For the website from the Gatsby template, specify
404.html
.
- In the Home page field, specify the absolute path to the file of the website home page. For the website from the Gatsby template, specify
- Click Save.
-
Create a hosting settings file in JSON format. For example:
{ "index": "index.html", "error": "404.html" }
Where:
index
: Absolute path to the file of the website home page.error
: Absolute path to the file the user will see in case of4xx
errors.
-
Run the following command:
yc storage bucket update --name <bucket_name> \ --website-settings-from-file <file_path>
Where:
--name
: Bucket name, which isgatsbytest.ru
in our example.--website-settings-from-file
: Path to the hosting settings file.
To make sure the bucket description now contains the hosting settings, run this command:
yc storage --name <bucket_name> bucket get --full
Result:
website_settings:
index: index.html
error: error404.html
redirect_all_requests: {}
If you don't have Terraform, install it and configure the Yandex Cloud provider.
Before you start, retrieve the static access keys: a secret key and a key ID used for authentication in Object Storage.
-
In the configuration file, describe the parameters of the resources you want to create:
provider "yandex" { token = "<OAuth>" cloud_id = "<cloud_ID>" folder_id = "<folder_ID>" zone = "ru-central1-a" } resource "yandex_storage_bucket" "test" { access_key = "<static_key_ID>" secret_key = "<secret_key>" bucket = "<bucket_name>" acl = "public-read" website { index_document = "index.html" error_document = "404.html" } }
Where:
access_key
: Static access key ID.secret_key
: Private access key value.bucket
: Bucket name.acl
: ACL access management parameters.website
: Website parameters:index_document
: Absolute path to the website home page file. This is a required parameter.error_document
: Absolute path to the file the user will see in case of4xx
errors. This is an optional parameter.
-
Make sure the configuration files are correct.
-
In the command line, go to the folder where you created the configuration file.
-
Run a check using this command:
terraform plan
If the configuration is described correctly, the terminal will display a list of created resources and their parameters. If the configuration contains any errors, Terraform will point them out.
-
-
Deploy cloud resources.
- Run this command:
terraform apply
- Confirm that you want to create the resources.
All the resources you need will then be created in the specified folder. You can check the new resources and their configuration using the management console
.
To set up hosting for a static website, use the update REST API method for the Bucket resource, the BucketService/Update gRPC API call, or the upload S3 API method.
Link the domain name
On the DNS sever, create a public DNS zone and a resource record which links your domain name to the bucket:
- In the management console
, go to the bucket you want to use your own domain for. - Go to the
Website tab. - In Hosting, under Domains in Cloud DNS, click Create record.
- In the window that opens, click Create zone and select the domain zone of the same name with the bucket, e.g.,
gatsbytest.ru.
(ending with a period). Click Create. - Click Create.
- Click Save.
Upload your website to the bucket
To build and upload a working version of the website to your bucket, use AWS CLI
Set up the AWS CLI
-
To install the AWS CLI, use the instructions
posted on the developer's site. -
Assign the service account the roles required for your project. For more information about roles, see the Identity and Access Management documentation.
-
To configure the AWS CLI, type the
aws configure
command. The command will request values for the following parameters:AWS Access Key ID
: ID of the static key created in the previous step.AWS Secret Access Key
: Contents of the static access key.Default region name
:ru-central1
.
Note
To work with Object Storage, always specify
ru-central1
as the region.
An incorrectly specified region will lead to an authorization error. -
Leave the other parameter values unchanged.
Install the S3 plugin
-
On your local machine, go to the
gatsby-starter-blog
website folder and run this command:npm i gatsby-plugin-s3
-
Open the
gatsby-config.js
file and add the plugin declaration to theplugins
section:plugins: [ { resolve: 'gatsby-plugin-s3', options: { bucketName: '<bucket_name>', region: 'us-east-1', customAwsEndpointHostname: 'storage.yandexcloud.net' } }, ... ]
Where
<bucket_name>
is the bucket name,gatsbytest.ru
in our example.Note
Do not change the region value as this may lead to an error.
-
Open the
package.json
file and add thedeploy
entry to thescripts
section:"scripts": { "deploy": "gatsby-plugin-s3 deploy --yes", ... }
Upload your website to the bucket
-
Compile the website by running this command:
sudo npm run build
-
Wait for the compilation to complete and upload your website to the bucket by running the following command:
sudo npm run deploy
-
Once the upload is complete, check that you can access your website using its domain name. Open your browser and go to:
http://<bucket_name>
Where
<bucket_name>
is the bucket name,gatsbytest.ru
in our example.
Configure HTTPS access
To configure access to your website over a secure protocol, get a security certificate and configure HTTPS access to the bucket.
Get Let's Encrypt® certificates
-
Add a new Let's Encrypt® certificate:
Management consoleCLITerraformAPI- In the management console
, select the folder where you want to add a certificate. - In the list of services, select Certificate Manager.
- Click Add certificate.
- In the menu that opens, select Let's Encrypt certificate.
- In the window that opens, enter a name for your certificate in the Name field.
- (Optional) In the Description field, enter a description for the certificate.
- In the Domains field, enter the name of the bucket where your website resides. In our example, it is
gatsbytest.ru
. - Select the type of domain rights check:
HTTP
. - Click Create.
-
Run this command:
yc certificate-manager certificate request \ --name gatsbycert \ --domains gatsbytest.ru
Where:
--name
: Certificate name--domains
: Certificate domains
-
In the Terraform configuration file, describe the parameters of the resource to create:
resource "yandex_cm_certificate" "le-certificate" { name = "<certificate_name>" domains = ["<domain>"] managed { challenge_type = "HTTP" } }
Where:
domains
: List of domains you need to create a certificate for. In our example, it isgatsbytest.ru
.challenge_type
: Type of domain rights check the domain owner must pass.
-
Create resources:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
A certificate will then be created in the specified folder. You can check the new certificate and its configuration using the management console
or this CLI command:yc certificate-manager certificate get <certificate_name>
To add a certificate, use the requestNew REST API method for the Certificate resource or the CertificateService/RequestNew gRPC API call.
The new certificate will appear in the certificate list with the
Validating
status. This status means that a request to issue a Let's Encrypt® certificate was created and you need to pass a domain rights check to process it successfully. - In the management console
-
Get the information required to complete the domain rights check:
Management consoleCLIAPI- In the management console
, select the folder you added the certificate to. - In the list of services, select Certificate Manager.
- Select the certificate to check from the list and click it.
- In the Check rights for domains section of the window that opens, you can find the details you need to pass the domain rights check: File location URL and Contents.
-
Run this command:
yc certificate-manager certificate get \ --id fpq6gvvm6piu******** \ --full
Where:
--id
: Certificate ID.--full
: Show a list of active domain rights checks.
Result:
id: fpq6gvvm6piu******** folder_id: b1g7gvsi89m3******** created_at: "2024-03-27T08:49:11.533771Z" name: gatsbycert type: MANAGED domains: - gatsbytest.ru status: VALIDATING updated_at: "2020-09-15T08:49:11.533771Z" challenges: - domain: gatsbytest.ru type: HTTP created_at: "2024-03-27T12:20:32.326Z" updated_at: "2024-03-27T12:30:16.709Z" status: PENDING message: Create a file in your web server's base directory. http_challenge: url: http://gatsbytest.ru/.well-known/acme-challenge/3LiH-nrTC7GdMbRgVqttEvdTODeNeaD0TtX******** content: 3LiH-nrTC7GdMbRgVqttEvdTODeNeaD0TtXteWgtAH8.ZHCju15sJiKBwT8G5FTl7UtfmJWp1gKNYYP********
To get the information required to pass the domain rights check, use the get REST API method for the Certificate resource or the CertificateService/Get gRPC API call with the
view=FULL
flag. - In the management console
-
On your local computer, create subfolders for the validation file in the
gatsby-starter-blog
website folder. For this, follow these steps:mkdir .well-known cd .well-known mkdir acme-challenge
-
Create a validation file based on the information you got. To do this, copy the final part of the validation file URL and use it as a name to create a file in the
acme-challenge
folder:cd acme-challenge nano <file_name>
Where <file_name> is the final part of the validation file URL.
For example, if this is your URL:
http://gatsbytest.ru/.well-known/acme-challenge/3LiH-nrTC7GdMbRgVqttEvdTODeNeaD0TtX********
Run the following:
nano 3LiH-nrTC7GdMbRgVqttEvdTODeNeaD0TtX********
Save the validation file contents to the file.
-
When you pass the domain rights check, the domain check status under Check rights for domains will change to
Valid
. The certificate will be issued and its status will change toIssued
.
Configure HTTPS access to your bucket
-
Add the certificate in the bucket's HTTPS access settings:
Management consoleYandex Cloud CLITerraformAPI- In the management console
, select the appropriate folder. - Select Object Storage.
- Click the bucket name,
gatsbytest.ru
in our example. - Go to the HTTPS tab.
- In the right-hand panel that opens, click Configure.
- In the Source field, select Certificate Manager.
- In the Certificate field, select the certificate from the list that opens.
- Click Save.
Run the following command:
yc storage bucket set-https --name <bucket_name> --certificate-id <certificate_ID>
Where:
--name
: Bucket name,gatsbytest.ru
in our example.--certificate-id
: Certificate ID in Certificate Manager.
Result:
source_type: SOURCE_TYPE_MANAGED_BY_CERTIFICATE_MANAGER certificate_id: fpqe2g0hfr0e********
To select a certificate from Certificate Manager:
-
Open the Terraform configuration file and add the
https
section to the bucket description:... resource "yandex_storage_bucket" "b" { bucket = "<bucket_name>" https { certificate_id = "<certificate_ID>" } } ...
Where:
bucket
: Bucket name,gatsbytest.ru
in our example.certificate_id
: certificate ID in Certificate Manager that will be used for the bucket.
-
Check the configuration using this command:
terraform validate
If the configuration is correct, you will get this message:
Success! The configuration is valid.
-
Run this command:
terraform plan
The terminal will display a list of resources with parameters. No changes will be made at this step. If the configuration contains any errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
into the terminal and click Enter.You can use the management console
to check the selected certificate.
To select a certificate from Certificate Manager, use the setHTTPSConfig REST API method for the Bucket resource or the BucketService/SetHTTPSConfig gRPC API call.
- In the management console
-
Check that you can now access your website over a secure protocol. Go to this address:
https://<bucket_name>
Where
<bucket_name>
is the bucket name,gatsbytest.ru
in our example.
Note
It may take some time to activate the settings.
How to delete the resources you created
To shut down the created resources and stop paying for them:
- Delete all objects from the bucket.
- Delete the bucket.