@amagaki/amagaki-plugin-kintaro
v2.1.3
Published
[![NPM Version][npm-image]][npm-url] [![GitHub Actions][github-image]][github-url] [![TypeScript Style Guide][gts-image]][gts-url]
Downloads
260
Readme
amagaki-plugin-kintaro
An experimental Amagaki plugin for integration with Kintaro, a headless CMS.
Features include:
- Dynamic routing: Create Amagaki routes from Kintaro collections.
- Translation importing: Import Kintaro translations to Amagaki locales.
Usage
- Install the plugin.
npm install --save @amagaki/amagaki-plugin-kintaro
Authenticate. See authentication for details.
Access the plugin in
amagaki.ts
:
import {BuilderPlugin, Pod, ServerPlugin} from '@amagaki/amagaki';
import {KintaroPlugin} from '@amagaki/amagaki-plugin-kintaro';
export default (pod: Pod) => {
const kintaro = KintaroPlugin.register(pod, {
repoId: '<Kintaro Repo ID>',
projectId: '<Kintaro Project ID>',
});
// Download and bind kintaro collections
const serverPlugin = pod.plugins.get('ServerPlugin') as ServerPlugin;
serverPlugin.register(async () => {
try {
await kintaro.bindCollection({
collectionPath: '/content/kintaro/',
});
} catch (err) {
console.warn(`[Kintaro Plugin] Unable to download; ${err}`);
}
});
// Create Amagaki routes from a Kintaro collection.
const setup = async () => {
await kintaro.addRouteProvider({
collectionId: '<Kintaro Collection ID>',
path: '/posts/${doc.basename}/${doc.fields.slug}/',
view: '/views/base.njk',
});
};
const builder = pod.plugins.get('BuilderPlugin') as BuilderPlugin;
builder.addBeforeBuildStep(async () => {
await setup();
});
const server = pod.plugins.get('ServerPlugin') as ServerPlugin;
server.register(async () => {
await setup();
});
// Import translations to your Amagaki project.
await kintaro.importTranslations({
stringKeyPatterns: [
'_label$',
'.label$',
'.text$',
'.title$',
'^cta_text_alt$',
'^description$',
'^headline$',
'^next$',
'^previous$',
'^site_name$',
'^title$',
],
});
};
Features
Dynamic routing
(To be documented)
- Similar to other tools that integrate with Kintaro, you may use the
?flush
query parameter to reset the cache. Add?flush
to reload Kintaro content without restarting the server.
Translation importing
(To be documented)
Authentication
There are two ways to authenticate. We recommend using the application default identity (option 1), but using a service account key file is acceptable as well.
Option 1: Using application default credentials
- Install the
gcloud SDK
. See instructions. - Login and set the application default credentials. Ensure you provide the required scopes.
gcloud auth application-default login \
--scopes=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/kintaro
- That's it! Now, Amagaki will use the signed in Google Account to fetch content.
Option 2: Using a service account key file
- Acquire a service account key file. You can do this interactively, from the IAM section of the Google Cloud Console, or you can do this via the
gcloud
CLI (see below for an example).
PROJECT=<Google Cloud Project ID>
# Create a service account named `amagaki`.
gcloud --project=$PROJECT \
iam service-accounts create \
amagaki
# Create a JSON key and download it to `key.json`.
gcloud --project=$PROJECT \
iam service-accounts keys create \
--iam-account amagaki@$PROJECT.iam.gserviceaccount.com \
key.json
- Ensure
key.json
is added to your.gitignore
. - Ensure Kintaro (workspace) is shared with the service account. Service accounts that have never accessed Kintaro before must be whitelisted.
- Pass
keyFile
to the plugin.
KintaroPlugin.register(pod, {
keyFile: 'key.json',
repoId: '<Kintaro Repo ID>',
projectId: '<Kintaro Project ID>',
});
Simulate webhooks
Kintaro does not support webhooks – as a result there is no inbuilt way to run builds when a workspace is published. As a workaround, you can deploy a Google Cloud Function to poll Kintaro for the last time a workspace was published. When a publish event is observed via the polling mechanism, a new cloud build is submitted.
Configuration
Ensure the following permissions are configured:
- The Cloud Function must be able to:
- Read Kintaro
- Read/write Cloud Datastore
- Submit Cloud Builds
- The Cloud Build must be able to:
- Read Kintaro
- The Cloud Scheduler task must be able to:
- Invoke the Cloud Function
Usage
- Create a
apps/kintaro-webhook-simulator/index.js
:
import {WebhookSimulator} from '@amagaki/amagaki-plugin-kintaro';
import functions from '@google-cloud/functions-framework';
functions.http('syncKintaroRepoStatus', WebhookSimulator.getCloudFunction({
// `branchName` to use when submitting the Cloud Build.
branchName: '<string>',
// GCP project that owns the Cloud Build trigger and Datastore instance. This should usually be omitted.
gcpProject: '<string | undefined>',
// Kintaro "project" ID. Same as a Kintaro "workspace". Should be left as `undefined` to trigger only published content.
kintaroProjectId: '<string | undefined>',
// Kintaro "repo" ID. Same as a Kintaro "site".
kintaroRepoId: '<string>',
// UUID of the Cloud Build trigger.
buildTriggerId: '<string>',
}));
- Create a
apps/kintaro-webhook-simulator/package.json
:
{
"main": "index.js",
"type": "module",
"dependencies": {
"@amagaki/amagaki-plugin-kintaro": "^2.0.1",
"@google-cloud/functions-framework": "^3.0.0"
}
}
- Deploy the Cloud Function using the
gcloud
CLI:
gcloud functions deploy \
syncKintaroRepoStatus \
--runtime nodejs16 \
--trigger-http
- Create a Cloud Scheduler task that runs the function every minute.
Configure this from the Cloud Scheduler page:
https://console.cloud.google.com/cloudscheduler?project=<GCP PROJECT ID>
Use the following configuration:
- Frequency:
* * * * *
- Target type:
http
- URL:
https://us-central1-<GCP PROJECT ID>.cloudfunctions.net/syncKintaroRepoStatus
- HTTP method:
GET
- Auth header:
Add OIDC token