Commit 1465381a authored by Matija Obreza's avatar Matija Obreza

Initial documentation

parent a32e0be5
......@@ -16,7 +16,8 @@
<project xmlns="" xmlns:xsi=""
......@@ -55,6 +56,7 @@
......@@ -626,8 +628,57 @@
<idprefix />
<!-- <imagesDir>images</imagesDir> -->
Genesys Backup and Disaster Recovery Manual
December 2015: Documentation commit {buildNumber}
:revnumber: {projectVersion}
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
This manual provides all information required to properly backup Genesys application,
configuration and data for a safe and valid recovery.
This document is written under the assumption you are familiar with basics of GNU/Linux
administration and shell scripting.
== Elasticsearch[Elasticsearch] is used
== Genesys configuration
=== Configuration files
Genesys Server {projectVersion} loads the following configuration file in the order
. <<application-properties,>>
. <<spring-properties,spring/>>
. <<genesys-properties,>>
The first two files are bundled with the project and provide sensible defaults to
ensure a functional configuration. They are located in the `WEB-INF/classes` folder.
Any modifications to the defaults settings must be added to the `` file.
The `` file makes available the project version and build information.
Do not modify!
`` contains the default configuration options for any Genesys Server instance.
You can access its contents directly at{buildNumber}/src/main/resources/spring/[ on]
Configuration for your instance of the server belong to `` file. This file is not
required and does not come with any Genesys distribution (not even source code).
This file needs to be created in a location that is included on the webapplication's CLASSPATH.
=== Configuration options
==== HTTP, CDN and cookie configuration
[cols="1,1,3", options="header"]
.HTTP-related configuration
|Default value
||localhost|The hostname part of the Genesys URL
|base.hostname|${}:8080|maven and Jetty run on port 8080 by default
|base.url|http://${base.hostname}|Genesys happily operates with relative URLs. The `base.url` is used
in email message templates and any other case where the full URL is needed.
|base.cookie-domain||Set the domain of the HTTP cookies. This allows us to share
cookies between all domains.
|base.cookie-secure|false|maven and Jetty don't use HTTPS by default. Switch this to `true` if you
plan to run on HTTPS protocol.
|base.cookie-http-only|false|AJAX calls from the browser sometimes require session information for
user authentication. Keep this value `false`.
|cdn.server|${base.url}|Default configuration does not use a CDN and defaults to the `base.url`.
|robots.allow|false|Setting this to `true` will produce a `/robots.txt` response that allows robots to index
the site.
==== Database configuration
Genesys requires a database to function. Feel free to choose from a number of databases supported by[Hibernate].
The production server runs on mysql-server-5.6 with InnoDB. We have seen
the server run on PostgreSQL database, but that's about it. Contact if you wish
to explore running the server on some other RDBMS.
[cols="1,1,3", options="header"]
.Database configuration options
|Default value
|db.url|...|Default mysql connect string used by most developers
|db.driverClassName|...|Defaults to Mysql Connector/J JDBC driver class name `com.mysql.jdbc.Driver`
|db.username|root|Database username
|db.showSql|false|Do not log SQL statements
|db.hbm2ddl|true|Apply changes to RDMBS based on current the application data model
|hibernate.dialect|org.hibernate.dialect. MySQL5InnoDBDialect|The[SQL dialect] that Hibernate can use when talking to the database
|c3p0.acquireIncrement|1|Acquire increment for SQL connections. We use 2 in production.
|c3p0.minPoolSize|1|Minimum number of SQL connections in the c3p0 pool We use 5 in production.
|c3p0.maxPoolSize|5|Maximum number of SQL connections in the c3p0 pool. We use 20 in production.
|c3p0.maxIdleTime|10|We use 30 in production.
===== Creating a mysql database
Connect to your mysql instance and create a new blank database *genesys2*:
# Create database
The `DEFAULT CHARSET UTF8` ensures that tables created in this database will use UTF8 character
encoding by default.
Create user *genesys* with password *pwd* that will access the database from *localhost*:
GRANT ALL ON genesys2.* TO 'genesys'@'localhost' IDENTIFIED BY 'pwd';
===== Database connection settings
Apply the relevant database configuration settings in `` file:
# genesys2 with mysql database
==== External Services
Genesys uses a number of external service APIs to provide users with advanced functionality.
[cols="1,1,3", options="header"]
.External APIs
|Default value
|google.consumerKey||Google+ sign in
|google.consumerSecret||Google+ sign in
|google.api.key||Google API key, register your application with the[Developers Console]
|google.url.shortener||Google URL shortener API
|captcha.privateKey|...|reCAPTCHA API private key.[Google reCAPTCHA]
|captcha.siteKey|...|reCAPTCHA API public or site key.[Google reCAPTCHA]
|captcha.publicKey|...|Obsolete, use `captcha.siteKey` instead.
|itpgrfa.easysmta.url||Easy-SMTA URL
|itpgrfa.easysmta.username|bar|Easy-SMTA account username
|itpgrfa.easysmta.password|foo|Easy-SMTA account password
|||The Google Analytics account for all pages.
|transifex.project|genesys-dev|[Transifex] project name
|transifex.username||Transifex username
|transifex.password||Transifex password
|transifex.base.api.url||Transifex API URL
|transifex.hook.key|this-is-a-test-hook-key|If you want to receive automatic notifications from Transifex, this is the hook.
|transifex.min.translated|80|Threshold of acceptable percentage translated for automatic acceptance.
==== Other stuff
[cols="1,1,3", options="header"]
.Other stuff
|Name|Default value|Description
|download.files.dir|./data/|Directory where files get stored.
|auto.createContent|false|Should default content be created on application startup? Set this to true
||22|The maximum length for abbreviated menu item titles.
==== Email and SMTP configuration
[cols="1,1,3", options="header"]
.SMTP configuration
|Name|Default value|Description
|mail.user.from|test@localhost|The email address used as the *From:* address
||test@localhost|Email address to which requests for material are always *CC'd*
||localhost|SMTP hostname
|mail.port|25|SMTP port
|mail.smtp.auth|true|Use SMTP authentication
|||Username for SMTP authentication
|mail.user.password||Password for SMTP authentication
|mail.smtp.ssl.enable|true|Enable SSL
|mail.smtp.starttls.enable|true|Enable STARTTLS
|mail.transport.protocol|smtp|Or `smtps`
|mail.async|true|Emails should be sent in asynchronous mode.
==== Clustering
[cols="1,1,3", options="header"]
.Clustering configuration
|hazelcast.instanceName|hz-genesys|Hazelcast instance name
||genesys-hz-3.5|Hazelcast group name
|hazelcast.password|hazelcasts|Password to join the Hazelcast group
|hazelcast.port|5701|TCP Port
|||AWS Autodetection access key
|||AWS Autodetection secret key
||eu-west-1|Limit search for nodes to the specified AWS region
||sg-hazelcast|Security group used to identify instances considered for Hazecast group membership
|elasticsearch.url|http://localhost:9200/|Connection to <<elasticsearch>>
==== Scheduler and Executor pools
[cols="1,1,3", options="header"]
.Pools and Schedulers configuration
|Name|Default value|Description
|executor.core.pool.size|4|Executor thread pool size
|executor.max.pool.size|16|Maximum thread pool size
|executor.queue.capacity|100|Capacity of the executor queue if all threads are busy
|scheduler.max.pool.size|16|Scheduler thread pool size
|scheduler.tokens.cleanup.hours|1|Frequency of tokens cleanup job execution
=== Other stuff
# Theme
# TileServer CDN
# TileServer Cache
Genesys Server Reference Manual
December 2015: Documentation commit {buildNumber}
:revnumber: {projectVersion}
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
Genesys PGR (Plant Genetic Resources) is a free online global portal accessible at
that allows the exploration of the world’s crop diversity through a single website.
This manual contains information required to configure, upgrade, run and manage a Genesys Server.
NOTE: Note...
TIP: Pro tip...
IMPORTANT: Don't forget...
WARNING: Watch out for...
CAUTION: Ensure that...
=== Download
Binary *genesys2-server* distribution packages are available on request. Please contact
=== Sources
*genesys2-server* is licensed under link:$$$$[the Apache V2 license].
The source code of *genesys2-server* can be found on
Backup and Disaster Recovery
This section provides information required to properly backup Genesys application,
configuration and data for a safe and valid recovery.
:leveloffset: 1
:leveloffset: 0
== Running Genesys
Genesys requires a working connection to a RDMBS. See Genesys Server <<database-configuration>> for information how to select
and configure the most appropriate database.
Setting up and running a server involves the following steps:
. <<installJetty,Download and install Jetty>>
. Obtain or <<quickBuild,build>> genesys2-server distribution package
. <<configureJetty,Configure Jetty for genesys2-server>>
. <<daemontools,Run Jetty as a service>> with daemontools
=== Download and install Jetty
Download a **stable-9** copy of[jetty] and unpack it
to your favorite location.
In the next few lines, you will download, unpack and move a Jetty distribution to /opt folder.
File ownership and permissions need to be adjusted.
$ cd /tmp
$ wget
# unzip the jetty distribution in the /tmp folder
$ unzip
$ ls -la jetty-distribution-9.3.6.v20151106/
# as root, move the distribution to /opt
$ cd /opt
$ sudo mv /tmp/jetty-distribution-9.3.6.v20151106 /opt/jetty
# Adjust ownership
$ sudo chown -R root.nogroup /opt/jetty
# Adjust permissions
$ sudo chmod -R g-w /opt/jetty
$ sudo chmod -R o-rwx /opt/jetty
=== Building the project
At the moment of writing, the `{projectVersion}` is {projectVersion}.
Obtain a copy of `genesys2-server-{projectVersion}` archive by
building the project. The zip can be found in target/ directory.
=== Install *genesys2-server* and configure Jetty
Unpack `genesys2-server-{projectVersion}` archive and move its contents into the jetty directory,
next to existing `demo-base` and `webapps` directories.
$ cd /opt/jetty
$ sudo unzip .../genesys2-server-{projectVersion}
$ ls -la genesys2-server-{projectVersion}-jetty/
Your customized configuration options go to `genesys2-server-\\{projectVersion}-jetty/resources/`.
$ sudo nano genesys2-server-{projectVersion}-jetty/resources/
Check <<genesys-configuration-options>> for the list of options.
Start jetty from the `genesys2-server-{projectVersion}-jetty` base
$ cd genesys2-server-{projectVersion}-jetty/
$ java -jar ../start.jar
Standard output stream (stdout) is used for logging.
This configuration uses HSQL database and is intended for testing genesys2-server.
To change the database settings, edit `genesys2-server-{projectVersion}-jetty/resources/` file:
# Genesys configuration with mysql database
All available configuration options and their default values are listed in <<genesys-configuration-options>>.
=== Building from source
Building and running the server requires[Java 8 SDK],[maven] and[compass].
. Clone[genesys2-server] to your computer
. Create a blank mysql database <<creating-a-mysql-database>>
. Configure database connection settings <<database-configuration>> in `src/main/resources/`
. Start Jetty with `mvn jetty:run`
== Application
Genesys is usually run in a[jetty] instance as described
in <<installing-genesys.adoc>>. This results in a very simple structure on the filesystem
that is easy to backup and will include the <<configuration>>.
== Configuration
Best practice requires keeping all custom changes to the <<genesys-properties.adoc>> in the
separate `` file.
In addition to Genesys configuration, all Jetty settings are located in the same base dir and are
easy to backup.
== Data
=== Database backup
=== File backup
=== Elasticsearch backup
== Validating backups
== Restoring Genesys from backups
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment