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:

Item	Service	Function
Backend	Kuroco	Manage content (images, text, member information, etc.) and create APIs.
Hosting	KurocoFront	Build GitHub-managed code on the server, allowing users to view it from their browsers.
Source code management	GitHub	Manage the source code for frontend displays.
Frontend	Nuxt.js	Write 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").

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.

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.

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

info

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.

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

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

note

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

caution

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.

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

You will be prompted to log in to GitHub.

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

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

tip

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.

tip

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

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

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

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].

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 name	Save to directory	Description
kuroco_front.json	/static	JSON file required for configuring settings such as redirection and basic authentication with KurocoFront.
build.yml	/.github/workflows	YAML 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.

tip

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.

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.

tip

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

• GitHub Docs: Learn GitHub Actions
• GitHub Docs: Workflow syntax for GitHub Actions

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.

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.

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].

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

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.

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).

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]).

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

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

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

Register an API

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

On the endpoint list screen, click [Add].

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

Now, navigate to the newly added API.

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

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

caution

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].

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.

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

Select the following settings and click [Add].

Item	Setting
Path		service
	Enabled/disabled	Enabled
Model	Category	Content
	Model	Topics
	Operation	Details
ext_group		Enable this option
topics_group_id		Group ID of your content structure (in this case 9)

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

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

tip

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:

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.

Next, set the BASE_URL written in the .env file as the baseURL of axios.
Rewrite the axios section in nuxt.config.js as follows:

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

To host on KurocoFront statically, turn off the server-side rendering feature on the server.
Add ssr: false, to nuxt.config.js.

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

export default {
  // 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: '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: {
    baseURL: process.env.BASE_URL
  },

  // Build Configuration: https://go.nuxtjs.dev/config-build
  build: {
  }
}

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/5/service/7 to your own endpoint URL.

<template>
  <div>
    <img :src="response.details.ext_1.url" width="800">
    <div>{{response.details.ext_2}}</div>
    <div>{{response.details.ext_3}}</div>

    <div v-for="n in response.details.ext_4" :key="n.slag" >
      <img :src="n.ext_4.url" width="400">
      <div>{{ n.ext_3 }}</div>
      <div>{{ n.ext_5 }}</div>
      <div>{{ n.ext_6 }}</div>
    </div>
  </div>
</template>

<script>
export default {
  async asyncData({ $axios }) {
    return { response: await $axios.$get('/rcms-api/5/service/7') };
  },
};
</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.

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].

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

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:

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:

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:

<template>
  <main>
    <header
      class="header"
      :style="{ backgroundImage: `url(${response.details.ext_1.url})` }"
    >
      <div class="header__text">
        <h1>{{ response.details.ext_2 }}</h1>
        <p>{{ response.details.ext_3 }}</p>
      </div>
    </header>

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

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

<script>
export default {
  async asyncData({ $axios }) {
    return { response: await $axios.$get('/rcms-api/5/service/7') };
  },
};
</script>

<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: 0.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: 0.75em;
}
.header {
  position: relative;
  width: 100%;
  height: 300px;
  background-position: center center;
  background-size: cover;
}
.header__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) {
  .header::before {
    width: 100%;
    height: 300px;
    position: absolute;
    top: 0;
    left: 0;
    background-color: rgba(0, 0, 0, 0.5);
    z-index: 1;
    content: '';
  }
  .header__text {
    position: absolute;
    top: 0;
    left: 0;
    color: #fff;
    z-index: 10;
  }
}
@media screen and (min-width: 768px) {
  body {
    font-size: 2em;
  }
  .header {
    height: 600px;
  }
  .header__text {
    width: 1200px;
    align-items: flex-end;
    margin: auto;
  }
  .header__text p {
    width: 600px;
  }
  .works__item {
    display: flex;
  }
  .works__item img {
    width: 400px;
    margin-right: 2em;
  }
  .about {
    text-align: center;
  }
}
</style>

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.

• Creating content list page with Kuroco and Nuxt.js
• Building a multi-language website with Kuroco and Nuxt.js
• Setting up inquiry forms with Kuroco and Nuxt.js
• Setting up a new member registration form with Kuroco and Nuxt.js
• Building a login page using Kuroco and Nuxt.js
• Integrating preview page with Kuroco and Nuxt.js