Quick Start

Last updated: oct.13, 2016 - 11:10:49

What's Hesperides

Hesperides is an open sourced tool, allowing to generate any kind of file type considering on one hand the templates, and the other hand the applications.

When to use it

It should be used as much as possible ! Concretely you can use it to generate :

  • html pages specified for your context
  • key/value files for your java application
  • json for your configuration datas
  • xml for your logback/log4 files
  • etc ...

Essential concepts

Several fundamental concepts underly and drive the Hesperides system. If you are a new user, knowing about them will help you use or integrate Hesperides into your environment.

Module and platform

First you have to create your resources :

  1. module
  2. template
  3. platform


Secondly you have to valuate your properties


Now you have created a module, a template, a platform and valuated your properties, you can generate your files. Hesperides offers two steps :

  1. /rest/files/applications/{application_name}/platforms/{platform_name}/{path}/{module_name}/{module_version}/instances/{instance_name} : Generate a json that contains for each file of your module :
    • the location of the generated file
    • the url to get the content of the generated file
    • the rights applied for the generated file
  2. /rest/files/applications/{application_name}/platforms/{platform_name}/{path}/{module_name}/{module_version}/instances/{instance_name}/{filename} : get the content of the generated file

Full example

Hesperides in 4 minutes !!


Docker image build

Building & running the Docker image from the sources


git pull https://github.com/voyages-sncf-technologies/hesperides
docker build -t hesperides .
docker run --rm -e SPRING_PROFILES_ACTIVE=noldap,fake_mongo hesperides

It can also be launched along a Mongo instance using docker-compose:

docker-compose -f docker/docker-compose.yml -f docker/docker-compose-mongo.yml up -d


git pull https://github.com/voyages-sncf-technologies/hesperides-gui
docker build -t hesperides-gui .
docker run --rm -it -p 80:80 -e API_ENDPOINT=... hesperides-gui

$API_ENDPOINT must be an URL to access the backend, like http://localhost:8080

Deploying on Heroku

This section provides a few guidelines on how to deploy Hesperides on Heroku, from our experience deploying the live demo.

An heroku.yml configuration file is provided in each repository as a starting point.

You will need to create 2 apps:

  • hesperides: the frontend, corresponding to the hesperides-gui repository
  • hesperides-back: the backend, corresponding to the hesperides repository

There is a reason behind this choice of Heroku apps naming: we wanted to have the frontend answering on the URL https://hesperides.herokuapp.com.

For each app, there are the steps to deploy it on Heroku:

  1. Sets the required Config Vars on the Heroku app Settings:
    • for the hesperides app: API_ENDPOINT: https://hesperides-back.herokuapp.com
    • for the hesperides-back app: SPRING_PROFILES_ACTIVE: noldap,fake_mongo
  2. Run the following commands in the corresponding cloned repository, using the Heroku CLI:
    heroku stack:set -a $app container
    heroku git:remote -a $app
    git push heroku master
    heroku ps:scale web=1 -a $app
    heroku ps -a hesperides
    heroku logs --tail -a hesperides
  3. Optionally, you can enable Heroku GitHub Deploys.

Configuring LDAP

You can either use the noldap Spring profile, that defines some dummy in-memory users, or use the ldap Spring profile and configure the following environment variables:

  • $LDAP_URL: required, example value: ldaps://ldap.example.com:636
  • $LDAP_DOMAIN: optional
  • $LDAP_USER_SEARCH_BASE: required, example value: dc=example,dc=com
  • $LDAP_USER_ROLE_BASE: required, example value: ou=Groups,dc=example,dc=com
  • $LDAP_TECH_GROUP_DN: optional, group of users with global Tech permissions, example value: cn=HESPERIDES_TECH,ou=Groups,dc=example,dc=com
  • $LDAP_PROD_GROUP_DN: optional, group of users with global Prod permissions, example value: cn=HESPERIDES_PROD,ou=Groups,dc=example,dc=com
  • $LDAP_BIND_DN: optional. If set, enable bindDn authentication; otherwise authentication on the LDAP server is performed with the credentials provided by the user when authenticating with Hesperides
  • $LDAP_BIND_PASSWORD: optional but required if $LDAP_BIND_DN is set