Beginner's guide to Kuroco

Introduction

Kuroco is an API-first headless CMS. Therefore, merely signing up for the free trial will allow your to display your site.
This tutorial explains the complete steps from sign-up to site display for those who are new to the headless CMS and Kuroco.

As an example, we will set up a website with the following structure:

ItemServiceFunction
BackendKurocoManage content (images, text, member information, etc.) and create APIs.
HostingKurocoFrontBuild GitHub-managed code on the server, allowing users to view it from their browsers.
Source code managementGitHubManage the source code for frontend displays.
FrontendNuxt.jsWrite the frontend part of the code for the site displays.

For the sake of simplicity, we will only build a landing page. Once you are familiar with the software, you can add forms, blog pages, multi-language support, and other features by following our documentation.

Deploying your Nuxt project to KurocoFront

Sign up for Kuroco's Free Trial

Sign up now for Kuroco's Free Trial. By default, the "basic membership site" package is selected, but feel free to choose any option if you want to build your site without using a package. Enter a site name of your choice (the example screenshot below uses "sample-service-site").

fetched from Gyazo

After signing up, you will receive an e-mail with the subject line "Your Kuroco account has been created!" Click the URL in the e-mail to access the Kuroco login screen.

fetched from Gyazo

When you log in to the Kuroco admin panel, you will see a "Top page" link at the bottom. At this stage, when you click this button, you will get a "404 Not Found (DEPLOYMENT NOT FOUND)" message. This is because the front-end has not been created yet.

fetched from Gyazo

Let's set the Kuroco admin panel aside for now and build the front-end.

Before you start

You should have already installed Nuxt.js using the npx command. Open a terminal and enter the command npx -v to check the version installed. If it has not been installed, download it from the Node.js website.

You will also need a GitHub account. Please sign up if you do not have one.

Install Nuxt.js

This tutorial uses Nuxt.js version v2.15.8.

After you have set up all the prerequisites, execute the following command in your designated project directory. Change sample-service-site to a name of your choice.

npx create-nuxt-app@4.0.0 sample-service-site

Next, you will be prompted to answer a list of configuration questions. For this tutorial, we will use the following settings:

Project name: sample-service-site
Programming language: JavaScript
Package manager: Npm
UI framework: None
Nuxt.js modules: Axios
Linting tools: None
Testing framework: None
Rendering mode: Universal (SSR / SSG)
Deployment target: Static (Static/Jamstack hosting)
Development tools: None
What is your GitHub username? (YOUR GIT USERNAME)
Version control system: Git

After entering all your responses, a sample-service-site directory will be created. Navigate to it as follows:

cd sample-service-site

Execute the command below to verify the display of the installed Nuxt.js.

npm run dev

You should see the following display in your terminal.

fetched from Gyazo

Access http://localhost:3000/ from your browser. You will see the screen below.

fetched from Gyazo

Now that you have installed Nuxt.js, you can display it in a local environment. Next, let's make this page viewable online.

Set up your GitHub repository

Login to GitHub and create a repository. After the repo has been set up, execute the following sequence of commands:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/GITHUB-USERNAME/REPOSITORY-NAME.git
git push -u origin main

Make sure to run Nuxt.js in the same directory you installed it in.

Replace GITHUB-USERNAME/REPOSITORY-NAME.git above with your own account information.

The above steps enable the Nuxt-installed folder to be managed by Git and push the files to remote repositories.

Integrate GitHub into Kuroco

To integrate GitHub, go to the Kuroco admin panel and click [KurocoFront] -> [GitHub] in the left sidebar panel.

Image (fetched from Gyazo)

Click [Authorize GitHub repository] to open the GitHub linking page.

Image (fetched from Gyazo)

You will be prompted to log in to GitHub.

Image (fetched from Gyazo)

After logging in, you will be redirected to the following screen.

Image (fetched from Gyazo)

Under "Repository access", select the repository you have just created.

Image (fetched from Gyazo)

The repository connection settings can be changed later. Select multiple repositories here if you are using multiple instances of Kuroco on one account, since there is only one GitHub App for Kuroco.

Note: You can only connect to repositories for which you have administrative permissions.

After you have selected your repository, click [Save].

Image (fetched from Gyazo)

You will then be prompted to log in to Kuroco again.

fetched from Gyazo

Once the connection has been established, you will be redirected to the KurocoFront screen. Select your target repository from the dropdown list and click [Update].

fetched from Gyazo

This concludes the integration of GitHub into Kuroco.

Deploy your code

To display the website at the URL https://SITE-KEY.g.kuroco-front.app/, deploy the code managed on GitHub to KurocoFront.

Add kuroco_front.json and the YAML file to the Nuxt.js project as follows:

File nameSave to directoryDescription
kuroco_front.json/staticJSON file required for configuring settings such as redirection and basic authentication with KurocoFront.
build.yml/.github/workflowsYAML file defining the workflow settings for GitHub Actions.

The respective contents of the files should be as follows.

/static/kuroco_front.json

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

Settings such as basic authentication and IP address restrictions are configured in kuroco_front.json.

For more information about kuroco_front.json, see FAQ: What is Kuroco_front.json?.

/.github/workflows/build.yml

For the contents of the file, copy and paste the content from the repository field on the KurocoFront screen.

fetched from Gyazo

If your GitHub branch is not main, or if you are using a custom domain, you may need to adjust the build command and branch name. However, for this tutorial, you can use the content as is.

For an introducation to what YAML files are and how to write them, see the following documents:

After you have added the files, push the changes to GitHub. This will execute the GitHub Actions to build and deploy.

When the building and deployment is complete, click [Top page] on the admin panel once again.

fetched from Gyazo

Instead of "404 Not Found (DEPLOYMENT NOT FOUND)", you should now see the initial display of the Nuxt.js project that you verified in your local environment earlier.

fetched from Gyazo

Now that you have learned how to display the first page of your website with Nuxt.js, you can build your site by adding contents in Kuroco and modifying their display and design in Nuxt.js.

Displaying contents managed by Kuroco

Now you are ready to build your site. Let's add content in Kuroco and display it with Nuxt.js.

Register your content

First, define your content structure in Kuroco's admin panel. In the left sidebar menu, click [Content structure].

fetched from Gyazo

On the content structure list screen, click [Add].

fetched from Gyazo

Enter a name of your choice in the content structure editor, configure the content items, and click [Add]. For this tutorial, we will use the settings shown below.

fetched from Gyazo

Next, group the contents and set the number of repetitions.
Return to the content structure editor, and click [Update] after you have configured all the settings.
When you select the child items (ID=5, ID=6) of the parent, you can set the name of the item specified as the parent (ID=4).

fetched from Gyazo

The next step is to add your content. In the sidebar menu, click [Content] and select the content structure you just created (in this case, we select [Business overview]).

fetched from Gyazo

On the content list screen, click [Add] in the upper right corner.

fetched from Gyazo

The content item you just defined will be displayed. Enter your content, including images and/or text, and click [Add].

fetched from Gyazo

Note down the topic group ID (9) and content ID (7) for later use.

fetched from Gyazo

fetched from Gyazo

Register an API

Next, register an API. In the Kuroco admin panel sidebar, click [API] -> [Default API].

fetched from Gyazo

On the endpoint list screen, click [Add].

fetched from Gyazo

Enter your title, version, and description, then click [Add].

fetched from Gyazo

Now, navigate to the newly added API.

fetched from Gyazo

First, we have to configure the API security settings. Click the [Security] button.

fetched from Gyazo

Select [Cookie] from the dropdown list and click [Save].

fetched from Gyazo

Note: With the cookie security option, if you are using a custom domain, you will need to prepare a front-end domain and an API domain, since some web browsers may not allow third-party cookies and you may not be able to log in.

See: Google delays blocking third-party cookies in Chrome until 2023

The next step is to configure the CORS settings. Click [Operation CORS].

fetched from Gyazo

Under "CORS_ALLOW_ORIGINS", click [Add origin] and enter the following:

  • http://localhost:3000/
  • Your front-end domain (in this case https://sample-service-site.g.kuroco-front.app/)

Under "CORS_ALLOW_METHODS", click [Add method] and enter the following:

  • GET
  • POST
  • OPTIONS

Then, click [Save] to apply the changes.

fetched from Gyazo

Now you can create an endpoint to retrieve the Business overview content you entered earlier. To do this, click [Add new endpoint].

fetched from Gyazo

Select the following settings and click [Add].

ItemSetting
Pathservice
Enabled/disabledEnabled
ModelCategoryContent
ModelTopics
OperationDetails
ext_groupEnable this option
topics_group_idGroup ID of your content structure (in this case 9)

fetched from Gyazo fetched from Gyazo fetched from Gyazo

This completes the configuration on the Kuroco side. You can access the endpoint you created to verify its responses. In this case, enter the content ID in the {topics_id} section and go to the following URL: https://sample-service-site.g.kuroco.app/rcms-api/5/service/7

fetched from Gyazo

Now you can build your site by writing the front-end description to retrieve and display the endpoint responses.

For a tutorial on how to verify API responses, see: How to check the data structure using Swagger UI.

Create an .env file

When you are using APIs, any URLs, API keys, etc. written directly in the .vue file may be seen by a third party. To prevent this security risk, before modifying your front-end, you need to create an .env file to store your private information.

Make an .env file directly under the Nuxt.js installation directory. In the file, write the URL to Kuroco's admin panel:

.env
BASE_URL = https://sample-service-site.g.kuroco.app

Substitute https://sample-service-site.g.kuroco.app above with your own API domain, which you can find on the endpoint list screen of the admin panel.

fetched from Gyazo

Next, paste the code below into nuxt.config.js so that it can reference your .env file.

  privateRuntimeConfig: {
    baseURL: process.env.BASE_URL
  },

The full content of nuxt.config.js is as follows:

nuxt.config.js
export default {
  // Target: https://go.nuxtjs.dev/config-target
  target: 'static',

  // Global page headers: https://go.nuxtjs.dev/config-head
  head: {
    title: 'sample-service-site',
    htmlAttrs: {
      lang: 'en'
    },
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { hid: 'description', name: 'description', content: '' },
      { name: 'format-detection', content: 'telephone=no' }
    ],
    link: [
      { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }
    ]
  },

  // Global CSS: https://go.nuxtjs.dev/config-css
  css: [
  ],

  // Plugins to run before rendering page: https://go.nuxtjs.dev/config-plugins
  plugins: [
  ],

  // Auto import components: https://go.nuxtjs.dev/config-components
  components: true,

  // Modules for dev and build (recommended): https://go.nuxtjs.dev/config-modules
  buildModules: [
  ],

  // Modules: https://go.nuxtjs.dev/config-modules
  modules: [
    // https://go.nuxtjs.dev/axios
    '@nuxtjs/axios',
  ],

  // Axios module configuration: https://go.nuxtjs.dev/config-axios
  axios: {
    // Workaround to avoid enforcing hard-coded localhost:3000: https://github.com/nuxt-community/axios-module/issues/308
    baseURL: '/',
  },

  // Build Configuration: https://go.nuxtjs.dev/config-build
  build: {
  },
  
  privateRuntimeConfig: {
    baseURL: process.env.BASE_URL
  },
}

Modify index.vue

When the .env file is ready for use, modify the frontend description via index.vue in the pages directory as follows:

Insert the response from the endpoint between the <script> </script> tags, and the html displaying the response content between the <template> </template> tags.

Also, change /rcms-api/3/service/3 to your own endpoint URL.

/pages/index.vue
<template>
  <div>
    <img :src="response.details.ext_col_01.url" width="800">
    <div>{{response.details.ext_col_02}}</div>
    <div>{{response.details.ext_col_03}}</div>

    <div v-for="n in response.details.ext_col_04" :key="n.slag" >
      <img :src="n.ext_col_04.url" width="400">
      <div>{{ n.ext_col_03 }}</div>
      <div>{{ n.ext_col_05 }}</div>
      <div>{{ n.ext_col_06 }}</div>
    </div>
  </div>
</template>

<script>
export default {
  async asyncData({ $axios, app }) {
    try {
      const response = await $axios.$get(
        process.env.BASE_URL + '/rcms-api/5/service/7'
        )
        console.log(response)
        return { response }
        } catch (e) {
          console.log(e.message)
          }
  },
}
</script>

Execute the command npm run dev in your terminal, and go to http://localhost:3000/ in your browser to verify the local environment display. You should see the contents you configured in Kuroco.

fetched from Gyazo

Deploy your code

Any changes in your local environment that you push to GitHub will be reflected in the front-end domain display. However, since .env files are not included in the push, they cannot be updated in this way. Instead, you need to use GitHub Actions to read and deploy the GitHub secret contents in .env format.

Register your GitHub secret

From your GitHub repository page, go to [Settings] -> [Secrets] -> [Actions], then click [New repository secret].

fetched from Gyazo

Enter the name and value of your secret and click [Add secret].

fetched from Gyazo

Modify the YAML file

The next step is to set up your YAML file to load the GitHub secret.

In /.github/workflows/build.yml, insert the following code just before jobs:.

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

The file should look something like this:

fetched from Gyazo

Afterwards, push the changes in /pages/index.vue and /.github/workflows/build.yml to GitHub.
When the deployment is complete, verify that your website looks like this:

fetched from Gyazo

Now you can output and retrieve contents from Kuroco via API for display on your website.

Design adjustments

The final step is to adjust your website design. Since this is completely done on the front-end, you can use your favorite CSS frameworks, link to external services, or use any kind of build you like.

For this tutorial, we modify the style section in index.vue as follows:

pages/index.vue
<template>
  <main>
    <header class="hero" :style="{backgroundImage: `url(${response.details.ext_col_01.url})`}">
      <div class="hero__text">
        <h1>{{ response.details.ext_col_02 }}</h1>
        <p>{{ response.details.ext_col_03 }}</p>
      </div>
    </header>

    <section>
        <h2>WORKS</h2>
        <ul>
            <li v-for="n in response.details.ext_col_04" :key="n.slag" class="works__item">
                <img :src="n.ext_col_04.url" />
                <div class="works__item__text">
                    <h3>{{ n.ext_col_05 }}</h3>
                    <p>{{ n.ext_col_06 }}</p>
                </div>
            </li>
        </ul>
    </section>

    <section class="about">
        <h2>ABOUT</h2>
        <p v-html="response.details.ext_col_07"></p>
    </section>
  </main>
</template>

<style>
body { 
    margin: 0;
    font-size: 1em;
    line-height: 1.5;
}
ul { 
  margin: 0;
  padding: 0;
  list-style: none;
}
img { max-width: 100%; }
section {
  max-width: 1200px;
  margin: 3em auto;
  padding: 0 20px;
}
h1 {
  margin: .5em 0;
  font-size: 1.8em;
}
h2 {
  margin: 2em auto;
  font-size: 1.5em;
  text-align: center;
}
h3 {
  margin: 1em auto;
  font-size: 1.2em;
}
p {
  margin: 1em 0;
  font-size: .75em;
}
.hero {
  position: relative;
  width: 100%;
  height: 300px;
  background-position: center center;
  background-size: cover;
}
.hero__text {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100%;
  padding: 0 20px;
}
.works__item:not(:first-child) {
    margin-top: 3em;
}
@media screen and (max-width: 767px) {
  .hero::before {
      width: 100%;
      height: 300px;
      position: absolute;
      top: 0;
      left: 0;
      background-color: rgba(0,0,0,.5);
      z-index: 1;
      content: "";
  }
  .hero__text { 
      position: absolute;
      top: 0;
      left: 0;
      color: #fff;
      z-index: 10;
  }
}
@media screen and (min-width: 768px) {
  body {
      font-size: 2em;
  }
  .hero {
    height: 600px;
  }
  .hero__text {
      width: 1200px;
      align-items: flex-end;
      margin: auto;
  }
  .hero__text p { width: 600px; }
  .works__item {
      display: flex;
  }
  .works__item img {
      width: 400px;
      margin-right: 2em;
  }
  .about { text-align: center; }
}
</style>

<script>
export default {
  async asyncData({ $axios, app }) {
    try {
      const response = await $axios.$get(
        process.env.BASE_URL + '/rcms-api/5/service/7'
        )
        console.log(response)
        return { response }
        } catch (e) {
          console.log(e.message)
          }
  },
}
</script>

fetched from Gyazo

https://sample-service-site.g.kuroco-front.app/

More information

For simplicity, this tutorial only covered how to create the landing page. Please refer to the tutorials below to learn how to build other pages for your site.

If you have any other questions, please use our contact form or Slack workspace.