Switching another site domain to Kuroco

This tutorial explains how to switch the domain from another site to Kuroco.

Switching the domain

1. Register an original domain on KurocoFront

In the left sidebar menu, click [KurocoFront] -> [Original domain/TLS certificate] and enter the domain you want to use in the Original domain field. Do not include a slash or directory at the end.

fetched from Gyazo

After entering the domain, click [Add].

fetched from Gyazo

2. Create a CNAME record

After the original domain has been authenticated, the Confirmation of domain ownership field will appear on the screen. Verify the DNS record in this field.

fetched from Gyazo

Configure the CNAME (canonical name) record according to the above information.

Note: The configuration of the DNS record varies depending on your domain registrar. Refer to the links below and contact your domain registrar's customer support for more information.

3. Update the front-end domain in the account settings

Next, plug your original domain into the front-end. Click [Environment] -> [Account] in the sidebar menu to go to the account settings screen.

fetched from Gyazo

The Front-end domain field should now display an option to change to the original domain you set up above. Verify and select this option, then click [Update].

fetched from Gyazo

Note: At this stage, you have not changed the "DNS records for using the domain", so your Kuroco-created site will not yet be displayed on the original domain you registered above. Accessing the original domain will direct you to your old site.

4. Register an original API domain (if applicable)

This step applies if you are using cookies in [API] -> [Security]. Otherwise, skip to 5. Allow CORS for your original domain.

In the sidebar menu, click [KurocoFront] -> [Original domain/TLS certificate] and enter the domain you want to use in the Original API domain field. Do not include a slash or directory at the end.

fetched from Gyazo

Note: The API domain must have a different sub-domain from the original domain.

For example:

  • Original domain:https://www.example.com
  • API domain:https://api.example.com

After entering your original API domain, verify the corresponding DNS records.

fetched from Gyazo

Configure the CNAME or address record accordingly.

Next, update the API domain. Click [Environment] -> [Account] to go to the account settings.

fetched from Gyazo

In the API domain field, select the API domain you added above and click [Update].

fetched from Gyazo

5. Allow CORS for your original domain

To add your original domain to the API CORS settings, select the desired API under the [API] dropdown list in the sidebar menu and click [Operation CORS] on the API screen.

fetched from Gyazo

In the CORS settings dialog, click [Add Origin] under the [CORS_ALLOW_ORIGINS] section.

fetched from Gyazo

Enter your original domain in the new textbox that appears and click [Save].

fetched from Gyazo

6. Modify files that directly describe the domain

If you have files directly describing the domain in the integrated GitHub repository, they need to be modified.

GitHub Actions YAML files

The YAML files used to integrate with GitHub Actions includes the domain and should be modified. To do so, click [KurocoFront] -> [GitHub] in the sidebar menu and copy the contents in the Repository field.
fetched from Gyazo

(See: How to deploy the source from GitHub to KurocoFront - 4. Place YAML file under .github/workflows)

.env file
If the root domain and/or API domain are written directly in the .env file, please modify it.

7. Modify the hosts file (optional)

As an optional step, you can modify the hosts file to verify your website display before updating the DNS records. Take note of the following points.

The address record for the hosts file can be found in the DNS records for the domain (If CNAME is not available) field in [KurocoFront] -> [Original domain/TLS certificate].

fetched from Gyazo

The above screenshot shows 4 address records, but you only have to enter 1 record in the hosts file.

hosts sample
151.101.XX.XXX www.example.com

After verifying the site display, make sure to restore the original hosts settings.

8. Create DNS records to use the domain

In the left sidebar menu, click [KurocoFront] -> [Original domain/TLS certificate]. Verify the DNS records for the domain (Recommended) or DNS records for the domain (If CNAME is not available) field.

fetched from Gyazo

Configure the CNAME or address record according to the above information.

Note: The configuration of the DNS record varies depending on your domain registrar. Refer to the links below and contact your domain registrar's customer support for more information.

Once the DNS is reflected, you will be able to access the Kuroco website through your original domain by clicking [Top page] in the sidebar menu.

fetched from Gyazo

More information

To learn more about using original domains and KurocoFront, refer to the documents below:

If you have any other questions, please contact us or check out Our Slack Community.