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.
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 followingbranches:
in the build.yml file with the branch name of your staging site. For this tutorial, we are changing this text frommain
tostg
.Load the GitHub secret.
Add the following statement just before jobs: in .github/workflows/staging.ymlenv:
BASE_URL: ${{secrets.BASE_URL}}Using kuroco_front.json for stage sites
The JSON file for using KurocoFront iskuroco_front.json
.
Therefore, we will add code to the YAML file to copykuroco_front_stg.json
tokuroco_front.json
, so thatkuroco_front_stg.json
will be used only whenstaging.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 todev
.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 iskuroco_front.json
.
Therefore, add a YAML file description to copykuroco_front_dev.json
tokuroco_front.json
only whendevelop.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.
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
Support
If you have any other questions, please contact us or check out Our Slack Community.