Skip to content

imperia Headless#

imperia CMS is classically operated as a decoupled CMS. This means that the editorial production of the content is spatially separated from the presentation of the content, it is usually located on different servers. With the increasing strength of web frameworks and their strong interlocking with data APIs, it is becoming more and more sensible to completely separate the presentation from the CMS and to offer the editorial content in a frontend-agnostic Content-API.

Content-API with Hasura#

In this guide you will learn how to run imperia as a headless CMS with a Hasura GraphQL API.

Prerequisite#

The following steps must be completed before you can follow the instructions: It is assumed that you already have a running imperia (DEV) installation available. It is best to run the API on a separate web server. However, you can also use the same server for testing purposes. The API server should have a PostgreSQL database, Docker and an imperia target system (LIVE) installed.

Setup Hasura-API#

Step 1: Obtain PostgreSQL variables#

Have the following variables of your PostgreSQL database ready: <DB_USER>, <DB_PASS>, <DB_HOST>, <DB_PORT> and <DB_NAME>.

Step 2: Run Hasura Docker-Container#

Run the following Docker command and replace your PostgreSQL variables in it to initialize the Hasura-API: 

docker run -d -p 8080:8080 -e HASURA_GRAPHQL_DATABASE_URL=postgres://<DB_USER>:<DB_PASS>@<DB_HOST>:<DB_PORT>/<DB_NAME> -e HASURA_GRAPHQL_ENABLE_CONSOLE=true hasura/graphql-engine:v1.1.0

Step 3: Create Database Schema#

To create the database schema for the Hasura API, navigate to root directory of the imperia target system (LIVE) and execute the following script invocation: 

perl site/bin/admin_graphql.pl -d | psql <DB_NAME>

Step 4: Set Hasura metadata#

To create the Hasura metadata you must run the following command: 

curl -d'{"type":"replace_metadata", "args":'`perl site/bin/admin_graphql.pl -s`'}' http://localhost:8080/v1/query

Step 5: Create API Config File#

Now you need to create a config file that describes the tables and columns you want to retrieve with the Hasura-GraphQL-API. The location of the config file is site/config/graphql.conf. You can view a sample configuration at site/config/graphql.conf.sample

Example for a table based on selection of documents: 

<table>
name = documents 
type = document
filter= "published_uris.directory ~ products"
provider_plugin = Default
<custom_columns>
    title = title:TEXT
    modified = __imperia_modified:INTEGER
</custom_columns>
</table>

Example for a table with all categories: 

<table>
name = categories
type = category
provider_plugin = Default
<custom_columns>
    <column>
    name = name
    data_type = TEXT
    tablecol = name
    </column>
    linguas = linguas:TEXT
</custom_columns>
</table>

Step 6: Populate the Database#

To populate the database underlying the GraphQL API with the existent content from imperia documents you must run: 

perl site/bin/admin_initialize_graphql.pl -tb

Step 7: Test GraphQL API endpoint#

Afterwards the GraphQL API endpoint should be available at: http://:8080/v1/graphql

Step 8: Test GraphQL API Console#

The Hasura console should be available at: http://localhost:8080/console