Tesseract LITE Manual

GS Cloud Inc.

by Fred Brooker (Filip Oščádal <oscadal@gscloud.cz>)

https://litedoc.gscloud.cz

1. Introduction

1.1. IDEA

1.2. Magnitude

1.3. Version

1.4. Minimum Viable Product

2. Installation

2.1. Requirements

2.2. Git repository

2.3. Ubuntu installer

3. First run

4. Structure

4.1. Folders

4.1.1. App

4.1.2. Cache

4.1.3. Data

4.1.4. Web views / Templates

4.1.5. Static assets

5. Configuration

5.1. Build

5.2. config.neon

5.2.1. Config Variables

5.3. Routers

5.3.1. Router Directives

6. MVP

6.1. Model

6.2. View

7. Deployment

8. Modding

8.1. Core

1. Introduction

Tesseract LITE is a web package developed by GS Cloud Inc. under the MIT license.

https://lite.gscloud.cz

1.1. THE IDEA

People like systems. Systems easy to use and reasonably maintainable. No complexity hard to setup, and then even harder to support. We need to edit resources online and offline. Our idea is to use miscellaneous production grade components and G Suite Sheets for data layers and localization.

And it blends well. :)))

1.2. Magnitude

  1. Model–view–presenter (MVP) architectural pattern.
  2. Ease of development, deployment and maintenance.
  3. Strong security, Google OAuth login only.
  4. Online management of non-interactive resources.
  5. Fast responsive templating engine, both for server and client.
  6. Caching, logging, debugging.
  7. Expandable, not dependent on one framework or library.
  8. If something breaks or support cease, it should be easy to replace that part.
  9. We use senior secure top grade Cloudflare + Knot resolver as a standard.
  10. Mind!

1.3. Version

Current version 1.0.* is considered stable beta, under development.

1.4. Minimum Viable Product

There is MVP bundled as folder www0 + app version 0.

https://litemin.gscloud.cz

2. Installation

2.1. Requirements

  1. Linux (developed on Ubuntu 16.04)
  2. Apache 2.4+ web server and modules: (* optional)
  1. cloudflare *
  2. expires
  3. headers
  4. php7.2
  5. rewrite
  6. ssl *
  1. Composer (important packages):
  1. altorouter/altorouter
  2. cakephp/cache
  3. league/csv
  4. league/oauth2-client
  5. league/oauth2-google
  6. monolog/monolog
  7. mustache/mustache
  8. nette/neon
  9. paragonie/halite
  10. tracy/tracy

2.2. Git repository

https://bitbucket.org/gscloud/tesseract_lite/src

git clone https://bitbucket.org/gscloud/tesseract_lite.git

2.3. Ubuntu installer

We have created scripts to install everything that we rely on:

https://bitbucket.org/gscloud/ubuntu_server_installer/src

3. First run

Run ./INSTALL.sh to set permissions and create missing folders.

Composer will download all missing dependencies too. No further settings are needed.

The rest of the functionality resides in the app config and routers.

Apache web root points to www folder.

4. Structure

4.1. Folders

4.1.1. App

MVP app is versioned under the app folder including configuration and classes.

You can switch version in index.php (recommended) or Bootstrap.php.

Any version string is possible.

This path can be overridden (constant).

4.1.2. Cache

The content of the cache folder can be erased anytime.

This path can be overridden (constant).

4.1.3. Data

The content of the data folder can be erased anytime, but you will likely destroy some valuable resources, like secure cookies or other App data. TAKE CARE!

This path can be overridden (constant).

4.1.4. Web views / Templates

Templates are stored within www folder and are hidden via .htaccess.

We start with a plain HTML template that works and loads other resources correctly, then rename it to .mustache.

Mustache templating engine supports includes, that reside in www/partials.

This path can be overridden (CONSTANT).

4.1.5. Static assets

Web resources are stored inside www folder (web root) and are controlled via .htaccess.

Every git commit has different version hash. We use that hash as a prefix using symbolic linking inside the cdn-assets folder, it points back to the web root (filesystem loop).

 MODEL  version hash is available as a parameter: cdn

Example:

<link rel="shortcut icon" href="{{cdn}}/ico/favicon.ico">

<link rel="shortcut icon" href="/cdn-assets/3f1b7414f1fa66af7778c14a316148bf8ee6712e/ico/favicon.ico">

5. Configuration

These parameters can be set inside index.php.

Bootstrap.php:

# folders

defined('ROOT')         || define('ROOT', __DIR__);

defined('DATA')         || define('DATA', ROOT.'/data');

defined('VERSION')      || define('VERSION', 'v1');

defined('APP')          || define('APP', ROOT.'/app/'.VERSION);

defined('DEBUG')        || define('DEBUG', FALSE);

defined('CACHE')        || define('CACHE', ROOT.'/cache');

defined('WWW')          || define('WWW', ROOT.'/www');

defined('WWW_PARTIALS') || define('WWW_PARTIALS', WWW.'/partials');

defined('TEMP')         || define('TEMP', '/tmp');

# files

defined('CONFIG')       || define('CONFIG', APP.'/config.neon');

defined('ROUTER')       || define('ROUTER', APP.'/router.neon');

# app

require APP."/app.php";

5.1. Build

App consists of config, routers, custom classes, presenters and web assets.

App depends on vendor classes controlled by Composer.

Run ./BUILD.sh to prepare a new local build.

Configuration path is related to APP and VERSION, this path can be overridden (constant).

5.2. config.neon

Every app is unique, so we have only one configuration file stored in NEON format as config.neon. Configuration can contain any user defined data, some are mandatory as internal variables.

5.2.1. Config Variables

variable

type

default

description

date_default_timezone

string

Europe/Prague

default time zone

project

string

UNKNOWN_PROJECT

project id

cache_profiles

array

  "csv" => "+5 minutes",

  "default" => "+30 seconds",

  "limiter" => "+10 seconds",

caching profiles

classes

array

  "IPresenter.php",

  "APresenter.php",

preloaded classes

secret_cookie_key

string

secret key filename

sites

array

sites per environment

locales

array

CSV locales stub

cfapikey

string

CloudFlare API key

cfemail

email

CloudFlare email

cfzoneid

string

CloudFlare zone id

cors_uri

URI

CROSS ORIGIN URI

google_ua_key

string

Google Analytics API access key

google_gtm

string

Google Tag Manager id

google_ua_id

string

Google Analytics id (UA)

onesignal_appID

string

OneSignal id

admin_groups

array

permission groups

admin_locales

array

G Suite sheets stub

goauth_clientID

string

Google OAUTH client ID

goauth_origins

array

Google OAUTH origins

goauth_redirects

array

Google OAUTH login pages

goauth_secret

string

Google OAUTH secret

5.3. Routers

Every app shares some routing functionality, we have three router files stored in NEON format as router_default.neon, router_admin.neon, router.neon. Routing sets must define views.

5.3.1. Router Directives

directive

type

default

description

admin

bool / string

0

1 = default/admin; admin group

autodoc

bool

1

automatic documentation ON/OFF

description

string

---

automatic documentation description

info

string

automatic documentation information

language

string

en

language (cs, en, de ...)

method

string

GET

HTTP methods separated by |

presenter

string

home

MVP presenter name

sitemap

bool

1

automatic sitemap ON/OFF

template

string

home

MVP view name

view

string

home

defaults only, sets main view id

6. MVP

6.1. Model

Model is a multidimensional array. The model is stored inside a singleton presenter class.

$app = $p::getInstance($data);

6.2. View

Views consist of Mustache templates.

7. Deployment

Syncing configuration is stored as _site_cfg.sh, see _site_cfg.sh.DIST for an example.

Run ./SYNC.sh to sync local build remotely using rsync.

DEST='/var/www/lite'

HOST='server.tld'

HOSTNAME='server'

USER='username'

8. Modding

8.1. Core

The core functionality can be modded in three entry points.

  1. /www/index.php
  2. /Bootstrap.php
  3. /app/v1/App.php