Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: corrected removeAbandonedTimeout and suspectTimeout in Tomcat 7 configuration (see discussion on syncope-dev)


Note
titleVersion Warning

The content below is for Apache Syncope <= 1.2 - for later versions check the "System Administration" chapter of the Reference Guide.

Table of Contents
styledecimal

Introduction

Once you have created your project, you can start adapting it to your own needs and requirements.

Deployment directory

Currently, Syncope needs two three base directories to be defined:

  • bundles - where ConnId bundles are stored (check what a connector bundle is);
  • log - where all system logs are written;
  • conf (optional) - where configuration files are located, if override is needed.
Warning

Bundles directory should only contain connector bundle JAR files.

The presence of any other file might cause the unavailability of any connector bundle in Apache Syncope.

For example, you can create directories as follows:

Code Block

$ mkdir /opt/syncope
$ mkdir /opt/syncope/bundles
$ mkdir /opt/syncope/log
$ mkdir /opt/syncope/conf

Internal storage

Internal storage is a database where all information and configurations are stored.

...

Code Block
core/src/main/resources/content.xml

.

Please note that Syncope core will populate internal storage with provided content only if the corresponding database is empty, i.e. does not contain any table or view.

...

as indicated in the following.

PostgreSQL

Code Block

jpa.driverClassName=org.postgresql.Driver
jpa.url=jdbc:postgresql://localhost:5432/syncope
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.hibernate.dialect.PostgreSQLDialect
dbUnitDataTypeFactory=org.dbunit.ext.postgresql.PostgresqlDataTypeFactoryapache.openjpa.jdbc.sql.PostgresDictionary
jpa.pool.validationQuery=SELECT 1
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
quartz.sql=tables_postgres.sql
audit.sql=audit.sql
database.schema=

This assumes that you have a PostgreSQL instance running on localhost, listening on its default port 5432 with a database

...

syncope

...

fully accessible by user

...

syncope

...

with password

...

syncope

...

.

MySQL

Code Block

jpa.driverClassName=com.mysql.jdbc.Driver
jpa.url=jdbc:mysql://localhost:3306/syncope?characterEncoding=UTF-8
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
dbUnitDataTypeFactory=org.dbunit.ext.mysql.MySqlDataTypeFactoryapache.openjpa.jdbc.sql.MySQLDictionary
jpa.pool.validationQuery=SELECT 1
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
quartz.sql=tables_mysql_innodb.sql
audit.sql=audit_mysql_innodb.sql
database.schema= 

This assumes that you have a MySQL instance running on localhost, listening on its default port 3306 with a database

...

syncope

...

fully accessible by user syncope with password syncope.

Code Block
syncope

with password

Code Block
syncope

It also assumes that the InnoDB engine is enabled in your MySQL instance - if this is not the case, then change the value for 'quartz.sql' to

Code Block
quartz.sql=tables_mysql.sql

MariaDB

Code Block
jpa.driverClassName=org.mariadb.jdbc.Driver
jpa.url=jdbc:mariadb://localhost:3306/syncope?characterEncoding=UTF-8
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.apache.openjpa.jdbc.sql.MariaDBDictionary
jpa.pool.validationQuery=SELECT 1
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
quartz.sql=tables_mariadb.sql
audit.sql=audit.sql
database.schema= 

This assumes that you have a MariaDB instance running on localhost, listening on its default port 3306 with a database syncope fully accessible by user syncope with password syncope.

Oracle

Code Block

jpa.driverClassName=oracle.jdbc.driver.OracleDriver
jpa.url=jdbc:oracle:thin:@localhost:1521:orcl
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.hibernate.dialect.Oracle10gDialect
dbUnitDataTypeFactory=org.dbunit.ext.oracle.Oracle10DataTypeFactoryapache.openjpa.jdbc.sql.OracleDictionary
jpa.pool.validationQuery=SELECT 1 FROM DUAL
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.oracle.OracleDelegate
quartz.sql=tables_oracle.sql
audit.sql=audit_oracle.sql
database.schema=SYNCOPE

This assumes that you have an Oracle instance running on localhost, listening on its default port 1521 with a database syncope under tablespace SYNCOPE fully accessible by user syncope with password syncope.

Code Block
syncope

under tablespace

Code Block
SYNCOPE

fully accessible by user

Code Block
syncope

with password

Code Block
syncope

You will also need to

  1. create directory

    Code Block
    core/src/main/resources/META-INF


  2. download Oracle mapping file for the version you are building (1_2_X, 1.1.X, 1.0.X)
  3. rename it to

    Code Block
    orm.xml

    and copy it under the directory created above

Microsoft SQL Server

Code Block
jpa.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
jpa.url=jdbc:sqlserver://localhost:1344;database=syncope;selectMethod=cursor;sendStringParametersAsUnicode=false
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.apache.openjpa.jdbc.sql.SQLServerDictionary
jpa.pool.validationQuery=SELECT 1
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.MSSQLDelegate
quartz.sql=tables_sqlServer.sql
audit.sql=audit_sqlserver.sql
database.schema=

This assumes that you have an SQL Server instance running on localhost, listening on its default port 1344 with a database syncope fully accessible by user syncope with password syncope.

You will also need to

  1. create directory

    Code Block
    core/src/main/resources/META-INF


  2. download MS SQL Server mapping file for the version you are building (1_2_X, 1.1.X, 1.0.X)
  3. Oracle mapping file,

    rename it to

    Code Block
    orm.xml

    and copy it under the directory created above

JEE container

Apache Tomcat 7

This assumes that you have got Apache Tomcat 7 installed in directory

...

$CATALINA_HOME

...

.

setenv.sh

Create

...

.

Note
titleDebian / Ubuntu warning

If you have installed Apache Tomcat 7 via Debian / Ubuntu package, you will also need to

  1. download the Tomcat JDBC Connection Pool JAR from Maven central repository, same version of the installed Tomcat 7
  2. copy the downloaded JAR file under /usr/share/java

Set Environment

GNU / Linux - Mac OS X

Create $CATALINA_HOME/bin/setenv.sh

...

with content (keep everything on a single line).

Code Block
JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server \
-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m \
-XX:MaxPermSize=256m -XX:+DisableExplicitGC"

Windows

Create %CATALINA_HOME%\bin\setenv.bat with content (keep everything on a single line).

Code Block
set JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server
-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m
-XX:MaxPermSize=256m -XX:+DisableExplicitGC

context.xml

Uncomment

...

<Manager

...

pathname=""

...

/>

...

in

...

$CATALINA_HOME/conf/context.xml

...

.

Optionally, define a datasource for internal storage (following example is for MySQL): please check that the connection parameters are same configure as configured above.

Syncope, when not finding a datasource called

Code Block
jdbc/syncopeDataSource

, will connect to internal storage by instantiating a new connection upon request: this is of course strongly discouraged for any production environment.

languagexml
Code Block

<Resource name="jdbc/syncopeDataSource" auth="Container" type="javax.sql.DataSource"
          factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" testWhileIdle="true"
          testOnBorrow="true" testOnReturn="true" validationQuery="SELECT 1" validationInterval="30000"
          maxActive="50100" minIdle="2" maxWait="10000" initialSize="2" removeAbandonedTimeout="1020"
          removeAbandoned="true" logAbandoned="true" suspectTimeout="1020"
          timeBetweenEvictionRunsMillis="5000" minEvictableIdleTimeMillis="5000"                         
          jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer" 
          username="syncope" password="syncope" driverClassName="com.mysql.jdbc.Driver"
          url="jdbc:mysql://localhost:3306/syncope?characterEncoding=UTF-8"/>

Be sure to put the JDBC driver JAR file under

...

$CATALINA_HOME/lib

...

for the Datasource you have defined above.

Other setup tasks

Uncomment element

Code Block
<resource-ref ... />

in

...

.

Glassfish 4.1

Update core glassfish-web.xml

When using a datasource for internal storage, be sure to add

Code Block
languagexml
  <resource-ref>
    <res-ref-name>jdbc/syncopeDataSource</res-ref-name>
    <jndi-name>jdbc/syncopeDataSource</jndi-name>
  </resource-ref>

assuming that your Glassfish instance provides a datasource named jdbc/syncopeDataSource.

right after </context-root> in core/src/main/webapp/WEB-INF/glassfish-web.xml.

JBoss AS 7.1

Note
titleVersion warning

Content of this paragraph applies to Apache Syncope < 1.2.0

Download this file, copy it under core/src/main/resources/ and replace

 

Code Block
languagexml
<entry key="openjpa.MetaDataFactory" value="org.apache.syncope.core.persistence.openjpa.JBossPersistenceMappingFactory(URLs=vfs:${project.build.directory}/cargo/configurations/jboss71x/deployments/${project.build.finalName}.war/WEB-INF/classes/, Resources=META-INF/orm.xml)"/>

with

 

Code Block
languagexml
<entry key="openjpa.MetaDataFactory" value="org.apache.syncope.core.persistence.openjpa.JBossPersistenceMappingFactory(URLs=vfs:/content/${project.build.finalName}.war/WEB-INF/classes/, Resources=META-INF/orm.xml)"/>

Fixing error messages at core startup

When core application starts up you will see many yet harmless error messages and stacktraces: this is due to an internal mechanism that looks for custom implementations of standard Apache Syncope interfaces.

If you want to remove such messages you can provide an override of the org.apache.syncope.core.init.ImplementationClassNamesLoader class: see an example here.

Wildfly 8.1

Note
titleVersion warning
Content of this paragraph applies to Apache Syncope >= 1.2.X

Download this file, copy it under core/src/main/resources/ and replace

Code Block
languagexml
<entry key="openjpa.MetaDataFactory" value="jpa(URLs=vfs:${project.build.directory}/cargo/configurations/jboss71x/deployments/${project.build.finalName}.war/WEB-INF/classes/, Resources=META-INF/orm.xml)"/>

with

Code Block
languagexml
<entry key="openjpa.MetaDataFactory" value="jpa(URLs=vfs:/content/${project.build.finalName}.war/WEB-INF/classes/, Resources=META-INF/orm.xml)"/>

Fixing error messages at core startup 

When core application starts up you will see many yet harmless error messages and stacktraces: this is due to an internal mechanism that looks for custom implementations of standard Apache Syncope interfaces.

If you want to remove such messages you can provide an override of the org.apache.syncope.core.init.ImplementationClassNamesLoader class: see an example here.

Use DataSource

When using a DataSource, a few additional adjustments are needed.

core web.xml

Change

Code Block
  <resource-ref>
    <res-ref-name>jdbc/syncopeDataSource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

to

Code Block
  <resource-ref>
    <res-ref-name>jdbc/syncopeDataSource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <lookup-name>java:/syncopeDataSource</lookup-name>
  </resource-ref>

assuming that you have defined a DataSource with JNDI name 'java:/syncopeDataSource' in JBoss configuration.

core jboss-deployment-structure

Add

Code Block
<module name="com.mysql"/>

right before

Code Block
</dependencies>

assuming that 'com.mysql' is the name of the JBoss module you have deployed for your JDBC Driver (MySQL in this case).

Oracle WebLogic 12

Update core web.xml

Change

Code Block
classpath*:/*Context.xml

to

Code Block
/WEB-INF/classes/*Context.xml

at the beginning of core/src/main/webapp/WEB-INF/web.xml.

, if you have defined a datasource.

Modify

...

Update core weblogic.xml

When using a datasource for internal storage, be sure to add

Code Block
  <resource-description>
    <jndi-name>syncopeDataSource</jndi-name>
    <res-ref-name>jdbc/syncopeDataSource</res-ref-name>
  </resource-description>

assuming that your WebLogic instance provides a datasource named syncopeDataSource.

before </weblogic-web-app> in core/src/main/webapp/WEB-INF/weblogic.xml.

Other setup tasks

Use datasource

Syncope, when not finding a datasource called jdbc/syncopeDataSource, will connect to internal storage by instantiating a new connection upon request: this is of course strongly discouraged for any production environment.

When using a container-managed datasource, be sure to uncomment the <resource-ref ... /> element in core/src/main/webapp/WEB-INF/web.xml.

Connect console to core

Modify console/src/main/resources/

...

console.properties

...

so that

Code Block
baseURL

provided properties reflects the scheme, hostname and port number where your JEE container is running and the URL context where Syncope core will be deployed.

For example, when running Apache Tomcat 7 and having

Code Block
1.0-SNAPSHOT

as project version (as created by Maven archetype)your JEE container on port 9080, you should set have

Code Block
baseURL

...

scheme=http
host=localhost
port=8080
rootPath=/syncope/rest/

Build and deploy

Assuming that you have created the two deployment directories defined above, just run

Syncope >= 1.2.0

Code Block

mvn clean package -Dconf.directory=/opt/syncope/conf -Dbundles.directory=/opt/syncope/bundles -Dlog.directory=/opt/syncope/log

At this point you can deploy

...

core/target/syncope

...

.war

...

and

...

console/target/syncope-console

...

.war

...

(where $PROJECT-VERSION is project version as created by Maven archetype) to your JEE container.

Test your

...

installation

  1. Point your favorite browser to administration console at Code Blockhttp://localhost:8080/syncope-console-$PROJECT-VERSION// (assuming that your JEE container is running on localhost, port 8080)
  2. Login as 'admin' / 'password'

...