Kurocoビギナーズガイド

はじめに

KurocoはAPIファーストのヘッドレスCMSであるため、フリートライアルに申し込んだだけではサイトの表示はされません。
本チュートリアルでは初めてヘッドレスCMSのKurocoを利用する方向けに、フリートライアル申込からサイトの表示までの手順を説明します。

ここでは例として、サービスの紹介サイトを下記の構成で作成します。

今回はヘッドレスCMSの理解を目的としてトップページのみの作成としますが、慣れてきたらフォームやブログページ、多言語対応等、ドキュメントを見ながら追加してみてください。

NuxtプロジェクトをKurocoFrontへデプロイする

Kurocoのフリートライアル申込

早速、Kurocoのフリートライアル に申し込みます。
リージョンを選択し、サイトキーはお好きな文字列を入力ください。
ここではリージョンを「アジア(東京)」、サイトキーを「sample-service-site」としました。

登録したメールアドレスに、「Kurocoサイト登録が完了いたしました！」のメールが届きます。
メールに記載されたURLをクリックするとKurocoのログイン画面が表示されるので、登録したメールアドレスとパスワードでログインします。

ログインすると、Kuroco管理画面が表示されます。
管理画面に[サイトを表示]のリンクがありますが、現時点ではクリックすると「404 Not Found (DEPLOYMENT NOT FOUND)」が表示されます。こちらはフロントエンドが作られていないためなので問題ありません。

Kurocoの管理画面は一旦このままで、次にフロントエンドの構築に進みます。

事前準備

Nuxt.jsはnpxのコマンドを使ってインストールしていきます。
ターミナルを開き、npx -vのコマンドでバージョンの確認ができますので、インストールされていない場合はnode.jsをインストールしてください。

また、GitHubのアカウントが必要になるので、持っていない場合は登録ください。

Nuxt.jsインストール

準備ができたらプロジェクトを管理する任意のディレクトリで下記のコマンドを実行します。
sample-service-siteの部分はお好きな名前に変更してください。

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

次に、複数の質問が聞かれるので回答します。 今回は下記のように入力しました。

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

全ての質問に回答するとsample-service-site ディレクトリが作成されますので、作成されたディレクトリに移動します。

cd sample-service-site

下記実行し、インストールしたNuxt.jsの表示を確認します。

npm run dev

ターミナルには下記のような表示がされます。

Listening:に表示されている http://localhost:3000/ にアクセスすると、下記の画面が確認できます。

以上でNuxt.jsのインストールとローカル環境での表示ができました。続いてこちらのページをweb上で表示できるようにしていきます。

GitHubリポジトリの準備

GitHubにログインして、リポジトリを作成します。リポジトリの準備ができたら下記のコマンドを順に実行します。

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/GitHubユーザー名/リポジトリ名.git
git push -u origin main

こちらの手順でNuxt.jsをインストールしたフォルダをGit管理化して、リモートリポジトリにファイルをプッシュできました。

GitHubとKurocoの連携

続いてGitHubとKurocoを連携します。
Kurocoの管理画面から[KurocoFront]->[GitHub]をクリックします。

[GitHubリポジトリと接続する]をクリックします。

GitHubへログインが求められますので、ログインをします。

ログインするとGitHubの画面が表示されます。

「Repository access」より先ほど作成したリポジトリを選択します。

リポジトリを選択したら、「Save」をクリックします。

再度Kurocoへのログインを求められますので、ログインをします。

接続が完了すると、KurocoFrontの画面に遷移するので、プルダウンから対象のリポジトリを選択して[更新する]をクリックします。

以上で、GitHubとKurocoの連携は完了です。

デプロイ

GitHubで管理しているコードをKurocoFrontにデプロイすることで、https://サイトキー.g.kuroco-front.app/のURLでwebサイトの表示ができます。

kuroco_front.json とYAMLファイル の2ファイルをNuxt.jsプロジェクトに追加します。

それぞれファイルの中身は下記のようにします。

/static/kuroco_front.json

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

Basic認証やIPアドレス制限等の設定はkuroco_front.jsonで行います。

/.github/workflows/build.yml

ファイルの中身はKurocoFront画面のリポジトリフィールドの内容をコピーして入力します。

GitHubのブランチがmain以外の場合や、独自ドメインを利用するような場合は、ビルドコマンドやブランチ名などを調整しますが、本チュートリアルの場合はこのまま使用できます。

ファイルの追加ができたら、変更をGitHubにプッシュします。プッシュするとGitHubActionが実行され、ビルド&デプロイされます。

ビルド&デプロイ完了後に、再度管理画面の[サイトを表示]をクリックします。

今度は「404 Not Found (DEPLOYMENT NOT FOUND)」ではなく、先ほどローカル環境で確認したNuxt.jsプロジェクトの初期の表示が確認できます。

以上でNuxt.jsの最初のページをwebサイトで表示できました。

Kurocoでコンテンツの追加をし、Nuxt.jsでコンテンツの表示やデザインの調整をすることでサイトの構築ができます。

Kurocoで管理したコンテンツを表示する

サイト構築の準備ができましたので、Kurocoでコンテンツの追加と、Nuxt.jsでKurocoのコンテンツの表示の作業をしていきます。

コンテンツの登録

まずはKurocoの管理画面でコンテンツを定義します。
[コンテンツ定義]をクリックします。

[追加]をクリックします。

コンテンツ定義編集画面でお好きな名前を入力し、コンテンツの項目を設定し、[追加する]をクリックします。
今回は下記のように設定しています。

続いてコンテンツのグループ化と繰り返し回数を設定します。
再度コンテンツ定義編集画面を開き、下記のように設定できたら[更新する]をクリックします。
子にする項目(ID=5, ID=6)の親項目を選択すると、親に指定された項目(ID=4)の名称を設定できます。

以上でコンテンツの内容を定義できましたので、次はコンテンツを追加していきます。
[コンテンツ]->[事業紹介]をクリックします。

[追加]をクリックします。

先ほど定義したコンテンツの項目が表示されますので、画像やテキストなど、コンテンツを入力して[追加する]をクリックします。
今回は下記のように登録しています。

追加したコンテンツ定義のID(7)とコンテンツのID(3)は後ほど利用するのでメモしておきます。

APIの登録

続いてAPIの登録をします。 Kurocoの管理画面から[API]->[Default]をクリックします。

[追加]をクリックします。

タイトル、版、説明を入力して[追加する]をクリックします。

追加したAPIに遷移します。

続いて、セキュリティの設定をします。
[セキュリティ]をクリックします。

[Cookie]を選択して[保存する]をクリックします。

続いて、CORSの設定をします。
[CORSを設定する] をクリックします。

CORS_ALLOW_ORIGINSの [Add Origin] をクリックし、下記を追加します。

• http://localhost:3000/
• フロントエンドドメイン (ここではhttps://sample-service-site.g.kuroco-front.app/)

CORS_ALLOW_METHODSの [Add Method] をクリックし、下記を追加します。

• GET
• POST
• OPTIONS

設定できたら[保存する]をクリックします。

次に先ほど作成したコンテンツ「事業紹介」を取得するエンドポイントを作成します。
[新しいエンドポイントの追加]をクリックします。

下記のように設定し、[追加]をクリックします。

以上で、Kuroco側の設定は完了です。
作成したエンドポイントにアクセスすると、エンドポイントからのレスポンスが確認できます。
今回の場合は{topics_id}の部分にコンテンツのIDを入力して、下記のURLで確認ができます。
https://sample-service-site.g.kuroco.app/rcms-api/3/service/3

こちらのレスポンスを取得して表示するようにフロントエンドの記述を書くことでサイトを構築できます。

envファイルの作成

フロントエンドの記述を調整する前に、まずはenvファイルを作成します。
APIを利用する際に、Vueファイルに直接URLやAPI KEY等を記載してしまうと第３者にみられてしまう可能性があります。 このようなセキュリティリスクを防ぐためenvファイルを作成し、他者に見られたくない情報はenvファイルに記載します。

Nuxt.jsインストールディレクトリ直下に .envを作成します。 .envにはKurocoの管理画面のURLを記載します。

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

URLはご自身のKuroco管理画面にあるAPIドメインをご記入ください。
APIドメインは、Kuroco管理画面の[API]ページより確認できます。

次に.envファイルに書いたBASE_URLをaxiosのbaseURLに設定します。
nuxt.config.jsのaxiosの部分を下記の記述に書き換えます。

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

KurocoFrontで静的にホスティングするために、サーバでの動的レンダリング機能をオフにしておきます。
nuxt.config.jsにssr: false,を追記します。

nuxt.config.js の全文は下記のようになります。

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: {
  }
}

index.vueの調整

envファイル利用の準備ができたら、フロントエンドの記述を調整します。pages のディレクトリにある index.vue を下記のように変更してください。

<script> </script>の部分で、エンドポイントからのレスポンスを得て、<template> </template>の部分でレスポンスの内容を表示するhtmlを記述しています。

/rcms-api/3/service/3の部分はご自身のエンドポイントの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/3/service/3') };
  },
};
</script>

ターミナルでnpm run devを実行し、 http://localhost:3000/にアクセスしてローカル環境で表示の確認をすると、下記のようにKurocoのコンテンツ表示が確認できます。

デプロイ

ローカル環境での変更をGitHubにpushすると、フロントエンドドメインでの表示にも反映されます。しかしながら、envファイルはpushの対象外となるため、このままでは更新ができません。

そこで、GitHubのシークレットに登録した内容をGitHubActionsでenvとして読込み、デプロイをします。

GitHub シークレットの登録

GitHubのリポジトリのページから、[Settings]->[Secrets]->[Actions] に遷移し、[New repository secret]をクリックします。

NameとValueを入力し、[Add secret]をクリックします。

YAMLファイルの調整

次にYAMLファイルでGitHubのシークレットを読み込むよう記述の追加をします。

/.github/workflows/build.yml の jobs:の直前に下記の記述を追加します。

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

下記のようになります。

準備ができたら /pages/index.vueと/.github/workflows/build.yml の変更をGitHubにpushします。
デプロイが完了すると、下記のようにWebサイト上でも表示の確認ができます。

以上でKurocoのコンテンツの内容をAPIで出力・取得し、webサイト上に表示できました。

デザインを調整する

最後にwebサイトのデザインの部分を調整します。
こちらは完全にフロントエンドでの作業になるので、普段利用しているCSSフレームワークを利用したり、外部のサービスと連携したり、ご自由に構築していただくことができます。

本チュートリアルではindex.vue でスタイルの調整をして次のようにしました。

<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/3/service/3') };
  },
};
</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/

参考

本チュートリアルではヘッドレスCMSの理解を目的として、トップページのみ作成をしました。
以下のドキュメントを参考に是非他のページも作成してみてください。

• KurocoとNuxt.jsで、コンテンツ一覧ページを作成する
• KurocoとNuxt.jsで、コンテンツ一覧ページにページネーションを実装する
• KurocoとNuxt.jsで、多言語サイトを構築する
• KurocoとNuxt.jsで、フォーム画面を構築する
• KurocoとNuxt.jsで、新規会員登録画面を構築する
• KurocoとNuxt.jsで、ログイン画面を構築する
• KurocoとNuxt.jsで、プレビュー画面を構築する