Using the KurocoFront app domain for your front-end staging site

Overview

Once you have your custom domain, you can use the default domain https://SITE-KEY.g.kuroco-front.app for your staging site. This tutorial explains how to do so by creating a separate GitHub branch.

What you'll learn

To make https://SITE-KEY.g.kuroco-front.app a stage site, perform the following steps.

• Implementing a staging site
• Setting up Development Environment
• Confirm file configuration

Before you start

We will implement the following branch and domain structure.

Environment	Branch	Domain	Purpose
Production	main	Custom Domain	Public-facing site
Staging	stg	https://SITE-KEY.g.kuroco-front.app	Site for pre-checks of design modifications, separate from backend
Development	dev	Custom Domain	Site for pre-checks of added functionality, separate from backend and frontend

Note: While this tutorial uses the branch names stg and dev, you may change them as desired.

Furthermore, this tutorial assumes that the procedures for Using your own custom domain name on KurocoFront and Using your own API domain with KurocoFront have been completed and that your site can be displayed with a custom domain.

Implementing a staging site

1. Create a branch for the staging site on GitHub

First, separate the production site and staging site displays in the GitHub branch. Go to your directory and execute the following command:

git checkout -b stg

2. Create kuroco_front.json for stage site

Create kuroco_front.json for the stage site in order to apply BASIC authentication to the stage site only.

Copy kuroco_front.json under /static directory and create kuroco_front_stg.json.

Describe Basic authentication as follows.

{
    "rewrites": [
        {
          "source": ".*",
          "destination": "/index.html"
        }
      ],
    "redirects": [],
    "basic":["user:pass"],
    "ip_restrictions":[]
}

3. Add a YAML file for the stage site

Next, add a YAML file to make the Github Actions work when you push changes in the stg branch. Click [KurocoFront] -> [GitHub] and copy the content in the GitHub Actions workflow file staging site text area.

Create a .github/workflows/staging.yml file with the copied contents

In addition, make the following modifications to the staging.yml file.

• Rename the Github Actions
  Change the first line to the following.
  name: Build and deploy to Kuroco front(stg)

• Change the branch that triggers the Github Actions execution
  replace the text following branches: in the build.yml file with the branch name of your staging site. For this tutorial, we are changing this text from main to stg.

• Load the GitHub secret.
  Add the following statement just before jobs: in .github/workflows/staging.yml

  env:
  BASE_URL: ${{secrets.BASE_URL}}

• Using kuroco_front.json for stage sites
  The JSON file for using KurocoFront is kuroco_front.json.
  Therefore, we will add code to the YAML file to copy kuroco_front_stg.json to kuroco_front.json, so that kuroco_front_stg.json will be used only when staging.yml is executed.
  Add the following description just before - name: Use Node.js in .github/workflows/staging.yml. (2 places)

  - name: Copy kuroco_front.json
    run: cp static/kuroco_front_stg.json static/kuroco_front.json 

The staging.yml file should look like this.

Save the file after the modification.

4. Push in the stg branch

Push the changes to GithHub. Click on the [Actions] tab on GitHub to check the build status and see that the build is running with the contents of staging.yml.

Once the build is completed, access the staging site from the logo on the Kuroco admin panel.

You will see that the staging site now requires basic authentication.

Click [Top page] in Kuroco to open the production site, which does not require basic authentication. As expected, the production site will not reflect any updates to the stg branch.

5. Merging changes in the stg branch into the main branch

Finally, merge the above into the main branch. The production build.yml file will be executed, but the modified file will be the following, so it will not affect the front-end display.

• staging.yml
• kuroco_front_stg.json

This completes the stage site setup.
The staging domain (https://SITE-KEY.g.kuroco-front.app) will now reflect any changes to the staging site in the stg branch.

Setting up Development Environment

1. Create dev branch

Separate the production and development environments on GitHub branches. After moving to the target directory, execute the following command from the command line.

git checkout -b dev

2. Create kuroco_front_dev.json

To apply BASIC authentication only to the development environment, create kuroco_front_dev.json for the development environment.

Copy /static/kuroco_front.json and create kuroco_front_dev.json.

Describe Basic authentication as follows.

{
    "rewrites": [
        {
          "source": ".*",
          "destination": "/index.html"
        }
      ],
    "redirects": [],
    "basic":["user:pass"],
    "ip_restrictions":[]
}

3. Adding a Subsite

Next, to separate the backend from the development environment, we will create a subsite from the Kuroco management screen.

Creating a Subsite

Click on [Environment Settings] -> [Site List].

Click on [Add].

Please click [Add] after setting as follows:

Item	Setting
Source site name	Select the production environment site
Site name	Development site
Site key	Any site key
Email address	Destination for completion email of site construction
Initial password	Any password
Company name	Your company name
Name	Your name

GitHub Integration

After creating the subsite, connect it to GitHub. Click [KurocoFront] -> [GitHub].

Click [Authorize GitHub Repository] and integrate with GitHub.

After connecting with GitHub, set the repository to the same as the production environment repository and click [Update].

4. Setting Up a Custom Domain and Custom API Domain

Set up a custom domain and custom API domain for the development environment. Set up the custom domain and custom API domain for the development environment from [Environment Settings] -> [Custom Domain/TLS Certificates].

Once the DNS settings are reflected and everything shows OK, the setup is complete.

Go to Environment Settings -> Account Settings and change the Front-end domain and API Domain.

5. Set up GitHub Secrets for the Development Environment

As the backend differs from the production environment, the API Domain will be different from the production environment in the development environment. In the Kuroco Beginner's Guide, the API Domain is set as a GitHub Secret. Therefore, add a GitHub Secret that sets the API Domain for the development environment.

Go to the repository page on GitHub, click on Settings -> Secrets -> Actions, and click on New repository secret.

Enter the following and click on Add secret.

Item	Value
Name	BASE_URL_DEV
Secret	API Domain for the development environment

6. Add develop.yml File

Next, add a YAML file for GitHub Actions to run when changes are pushed to the dev branch. From the Kuroco management screen for the development environment created earlier, click on [KurocoFront] -> [GitHub]. Copy the contents of the "GitHub Actions workflow file Front-end Domain" text area.

Create a .github/workflows/develop.yml file with the copied content.

Then make the following modifications to the develop.yml file:

• Change the name of the Github Actions Change the following line in the first line: name: Build and deploy to Kuroco front(dev)

• Change the branch that triggers Github Actions execution Modify branches: to the branch name for the development environment. In this case, modify it to dev.

• Load GitHub secrets Add the following description before the jobs: section in .github/workflows/develop.yml:

  env:
  BASE_URL: ${{secrets.BASE_URL_DEV}}

• Use kuroco_front_dev.json for the development environment The JSON file used to use KurocoFront is kuroco_front.json.
  Therefore, add a YAML file description to copy kuroco_front_dev.json to kuroco_front.json only when develop.yml is executed.
  Add the following description before - name: Use Node.js in .github/workflows/develop.yml (in two places):

  - name: Copy kuroco_front.json
    run:  cp static/kuroco_front_dev.json static/kuroco_front.json 

The develop.yml file will be as follows:

Save the file when the modifications are complete.

7. Push changes to dev branch

Push the changes made so far to GitHub. When you click on the "Actions" tab in GitHub, you can check the status of the build and see that the build is being executed with the contents of develop.yml.

Once the build is complete, access the development environment site from the [View site] button on the Kuroco management screen.

Other than the BASIC authentication, the display will be the same as the production environment.

8. Merge changes from dev branch to main and stg branches

Merge the above contents into the main and stg branches. The build.yml file and staging.yml file will be executed, but the following files have been changed, so there will be no impact on the front-end display.

• develop.yml
• kuroco_front_dev.json

With this, the development environment setup is complete. From now on, the changes made in the development environment branch (in this case, dev) and the management screen of the development environment site will be reflected in the development environment site.

Synchronize data between development and production environments

If there is a significant difference in data between the production and development environments, or if you want to reflect updates and additions made in the development environment to the production environment all at once, you can use the synchronization function.

Click [Edit] of the site that will be the synchronization destination from the Site List.

Select the Sync source site key in the Synchronization item, check the "Sync immediately" checkbox, and update.

When "Updated." is displayed, synchronization is complete.

danger

If you synchronize in the wrong direction, all necessary data will be overwritten. Therefore, we recommend that you back up your data as needed.

Checking the File Structure

Once the preparation for using the development environment is complete, the following files should exist in any branch. If it's not working properly, please check if the file structure is correct.

.github\workflows
  - build.yml
  - develop.yml
  - staging.yml
static
  - kuroco_front_dev.json
  - kuroco_front_stg.json
  - kuroco_front.json

Environment Variable Configuration

It is common to use different environment variables for development and production environments. In this tutorial, we explained how to store the API domain in GitHub secrets and switch between them. However, if you have a large number of environment variables, using environment variable configuration files can reduce the effort required for verification and updates.

However, since you can check the variables from the GitHub repository, you should choose whether to use GitHub secrets or environment variable configuration files based on the required level of confidentiality.

Creating Environment Variable Configuration Files

Create the following environment variable configuration files and apply them to each environment.

File Name	Purpose
.env.production.js	Environment variable configuration for production environment
.env.staging.js	Environment variable configuration for staging environment
.env.develop.js	Environment variable configuration for development environment

First, create each file with the following content:

.env.production.js

module.exports = {
  SITE_TITLE: 'Kuroco Sample Site',
  META_TITLE: 'Kuroco Sample Site',
  SITE_DESCRIPTION: 'A sample site created with reference to the Kuroco Beginner\'s Guide.',
  RSS_SITE_TITLE: 'Kuroco Sample',
  RSS_SITE_DESCRIPTION: 'Start using Kuroco with the Kuroco Beginner\'s Guide',
  ROBOTS: 'index',
}

.env.staging.js

module.exports = {
  SITE_TITLE: '[STG]|Kuroco Sample Site',
  META_TITLE: '[STG]|Kuroco Sample Site',
  SITE_DESCRIPTION: '[STG]|A sample site created with reference to the Kuroco Beginner\'s Guide.',
  RSS_SITE_TITLE: '[STG]|Kuroco Sample',
  RSS_SITE_DESCRIPTION: '[STG]|Start using Kuroco with the Kuroco Beginner\'s Guide',
  ROBOTS: 'noindex',
}

.env.development.js

module.exports = {
  SITE_TITLE: '[DEV]|Kuroco Sample Site',
  META_TITLE: '[DEV]|Kuroco Sample Site',
  SITE_DESCRIPTION: '[DEV]|A sample site created with reference to the Kuroco Beginner\'s Guide.',
  RSS_SITE_TITLE: '[DEV]|Kuroco Sample',
  RSS_SITE_DESCRIPTION: '[DEV]|Start using Kuroco with the Kuroco Beginner\'s Guide',
  ROBOTS: 'noindex',
}

Updating the YAML File

Define NODE_ENV using the env section of the YAML file.

env:
  BASE_URL: ${{secrets.BASE_URL}}

Add the following lines below this section:

build.yml

env:
  BASE_URL: ${{secrets.BASE_URL}}
  NODE_ENV: production

staging.yml

env:
  BASE_URL: ${{secrets.BASE_URL}}
  NODE_ENV: staging

develop.yml

  BASE_URL: ${{secrets.BASE_URL_DEV}}
  NODE_ENV: development

Updating nuxt.config.js

Since the NODE_ENV will contain the string specified in the YAML file, we can use this to load the environment-specific configuration files in nuxt.config.js.

Update nuxt.config.js as follows. Feel free to include other necessary configurations besides the site title in the header.

const environment = process.env.NODE_ENV || 'development';
const envSettings  = require(`./.env.${environment}.js`);

export default {
  env: envSettings,

  // Disable server-side rendering: https://go.nuxtjs.dev/ssr-mode
  ssr: false,
  // Target: https://go.nuxtjs.dev/config-target
  target: 'static',

  // Global page headers: https://go.nuxtjs.dev/config-head
  head: {
    title: envSettings.SITE_TITLE,
    htmlAttrs: {
      lang: 'en'
    },
    meta: [
      { charset: 'utf-8' },
  ・
  ・
  ・

Verifying Environment Variable Integration

Apply the changes to each environment, and after the build is completed, verify the display for each environment.

If the site title specific to each environment is displayed as shown below, the process is complete.

• Production
• Staging
• Development

Related Documents

• Beginner's guide to Kuroco
• Using your own custom domain name on KurocoFront
• Using your own API domain with KurocoFront