Tableaux

Tableaux (pronounced /ta.blo/) is a restful service for storing data in tables. These tables can have links between them.

Getting Started

Preparing the environment

To get a working setup, you need a jdd. The easiest way to work with different java versions is to use jEnv. It also works out of the box with gradle. If jEnv doesn't pick up the locally configured JDK automatically you can use the following command to set it up manually:

jenv enable-plugin gradle

To check if gradle is working, you can use the following command, which will print all the infos and versions:

gradlew -v

> ------------------------------------------------------------
> Gradle 7.4.1
> ------------------------------------------------------------
> 
> Build time:   2022-03-09 15:04:47 UTC
> Revision:     36dc52588e09b4b72f2010bc07599e0ee0434e2e
> 
> Kotlin:       1.5.31
> Groovy:       3.0.9
> Ant:          Apache Ant(TM) version 1.10.11 compiled on July 10 2021
> JVM:          17.0.2 (Homebrew 17.0.2+0)
> OS:           Mac OS X 12.2.1 x86_64

Setup

At first you need to setup your database and create a new conf.json based on ./conf-example.json. After that you can need to call POST /system/reset once to initialize system tables. If you wish you can fill in the demo data with POST /system/resetDemo.

Update DB schema (optionally)

If you upgrade from an older schema version you need to call POST /system/update before that. Schema will be upgraded automatically.

Auth

There are three different auth modes:

• 1. no auth (legacy)
• 2. manual auth with bearer token validation (JWT)
• 3. automatic keycloak auth discovery (JWT) - preferred

Auth modes 2. and 3. of Tableaux are secured by a JWT based authentication. The JWT (signed with a private key) is verified by the public key of the auth service. In manual auth mode 2. the public key is configured in the conf file (see ./conf-example-manual-auth.jsonc), in automatic auth mode 3. the public key is discovered via the auth service also configured in the conf file (see ./conf-example.jsonc)

The auth mode 1. is a legacy mode for testing or for running the service behind a different auth service. In this mode the incoming request is not verified. The user (e.g. for history entries) must be set via cookie userName. Legacy mode is activated, if auth key in config is missing.

Build & Test

Tableaux uses gradle to build a so called fat jar which contains all runtime dependencies. You can find it in build/libs/tableaux-fat.jar. The gradle task build needs a running PostgreSQL and the conf-test.json must be configured correct. Requests in auth tests must contain an accessToken. For simplicity this accessToken is generated within a test helper with a hardcoded key pair. For the accessToken to match the pub key, the auth configuration for testing must always be the same as configured in conf-test-example.json.

./gradlew clean build

Build without running tests:

./gradlew clean assemble

Tests (with custom config)

Tests use their own separate config, default configuration file is conf-test.json. Specific config can be passed via arguments.

Run tests:

./gradlew test -Pconf='custom.json'

To run a single test use the following command:

# full package and test name or wildcard with *, e.g.:
./gradlew test --rerun-tasks --tests="*deleteTable_validRole*" --info"

Run as fat jar

To execute the fat jar call it like this from project root:

java -jar ./build/libs/grud-backend-0.1.0-fat.jar -conf ../../conf.json
# with custom logging properties
java -jar -Djava.util.logging.config.file=./local_logging.properties ./build/libs/grud-backend-0.1.0-fat.jar -conf ./conf.json

Run in development

./gradlew run

or with automatic redeploy on code changes

./gradlew runRedeploy

Run with different conf file

./gradlew run -Pconf='other.json'

Authentication and permission handling

TODO add documentation for authentication and permission handling. Currently the docs are filed in confluence and hackmd.io.

Feature Flags

Feature flags are used to enable or disable certain features. They have to be configured in the configuration file. Feature flags are:

• isRowPermissionCheckEnabled: Enable or disable row permission checks (default: false)
• isPublicFileServerEnabled: Enable or disable the public file server. If enabled, files are accessible without authentication (default: false)

Highlevel Features

• Content Creation System
• Content Translation System
• Digital Asset Management
• Editing Publishing Workflow
• Workspaces & Custom Projections

License

Copyright 2016-present Campudus GmbH.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.