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.

For example, you can create directories as follows:

$ 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.

...

as indicated in the following.

PostgreSQL

jpa.driverClassName=org.postgresql.Driver
jpa.url=jdbc:postgresql://localhost:5432/syncope
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.apache.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
logbackaudit.sql=postgresqlaudit.sql
database.schema=

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

syncope

syncope fully accessible by user

...

syncope

...

with password

...

syncope.

MySQL

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.apache.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
logbackaudit.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.

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

quartz.sql=tables_mysql.sql

.

...

MariaDB

jpa.driverClassName=oracleorg.mariadb.jdbc.OracleDriverDriver
jpa.url=jdbc:oraclemariadb:thin:@localhost:1521:orcl//localhost:3306/syncope?characterEncoding=UTF-8
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.apache.openjpa.jdbc.sql.OracleDictionaryMariaDBDictionary
quartzjpa.pool.jobstore=validationQuery=SELECT 1
#note: other connection pool settings can also be configured here, see persistenceContext.xml
quartz.jobstore=org.quartz.impl.jdbcjobstore.oracle.OracleDelegateStdJDBCDelegate
quartz.sql=tables_oraclemariadb.sql
logbackaudit.sql=oracleaudit.sql
database.schema=SYNCOPE
 

This assumes that you have an Oracle a MariaDB instance running on localhost, listening on its default port 1521 3306 with a database

syncope

under tablespace

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 Oracle mapping file for the version you are building (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

database syncope fully accessible by user syncope with password syncope.

Oracle

jpa.driverClassName=oracle.jdbc.OracleDriver
jpa.url=jdbc:oracle:thin:@localhost:1521:orcl
jpa.username=syncope
jpa.password=syncope
jpa.dialect=org.apache.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

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
quartz.jobstore=org.quartz.impl.jdbcjobstore.MSSQLDelegate
quartz.sql=tables_sqlServer.sql
logback.sql=sqlserver.sql

This assumes that you have an SQL Server Oracle instance running on localhost, listening on its default port 1344 1521 with a database

syncope

syncope under tablespace 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 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

JEE container

Apache Tomcat 7

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

Set Environment

GNU / Linux - Mac OS X

Create $CATALINA_HOME/bin/setenv.sh with content (keep everything on a single line).

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).

Microsoft SQL Server

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. 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.

Set Environment

GNU / Linux - Mac OS X

Create $CATALINA_HOME/bin/setenv.sh with content (keep everything on a single line).

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).

set JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -

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

...

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

<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="100" minIdle="2" maxWait="10000" initialSize="2" removeAbandonedTimeout="2000020"
          removeAbandoned="true" logAbandoned="true" suspectTimeout="2000020"
          timeBetweenEvictionRunsMillis="5000" minEvictableIdleTimeMillis="5000"
          jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
          username="syncope" password="syncope" driverClassName="com.mysql.jdbc.Driver"
          usernameurl="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.

Glassfish 3.1

Add JVM option

-Dcom.sun.enterprise.overrideablejavaxpackages=javax.ws.rs,javax.ws.rs.core,javax.ws.rs.ext

Update core glassfish-web.xml

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

  <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

Use JBossPersistenceMappingFactory

Syncope < 1.2.0

Download this file, copy it under

core/src/main/resources/

and replace

...

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.

Glassfish 4.1

Update core glassfish-web.xml

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

  <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

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

<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)"/>

<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)"/>

...

with

...

...

Download this file, copy it under

...

 core/src/main/resources/

...

 and replace

<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

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

Set console's jboss-deployment-structure.xml

Download this file and copy it under

console/src/main/webapp/WEB-INF

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

  <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

  <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>

...

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

  <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.

<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> 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/configuration.properties so that 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 your JEE container on port 9080, you should have

scheme=http
host=localhost
port=9080
path=/syncope/rest/

Disable console debug

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 coreOnce you are ready to deploy, you might like to get rid of Wicket debug features provided by the console. Edit console/src/main/webapp/WEB-INF/web.xml.

Connect console to core

Modify console/src/main/resources/console.properties so that provided properties reflects the scheme, and change development to deployment as in the following configuration fragment (from 1.1 onwards you will have to explicitly add this):hostname and port number where your JEE container is running and the URL context where Syncope core will be deployed.

For example, when running your JEE container on port 9080, you should have

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

<context-param>
     <param-name>configuration</param-name>
     <param-value>deployment</param-value>
</context-param>

Build and deploy

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

Syncope >= 1.2.0

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 to your JEE container.

...

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