Introduction
Once you have created your project, you can start adapting it to your own needs and requirements.
Deployment directory
Currently, Syncope needs two base directories to be defined:
- bundles - where ConnId bundles are stored (check what a connector bundle is);
- log - where all system logs are written.
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:
$ mkdir /opt/syncope $ mkdir /opt/syncope/bundles $ mkdir /opt/syncope/log
Internal storage
Internal storage is a database where all information and configurations are stored.
You may want to setup some default content to be loaded on internal storage upon schema creation: for this you need to edit
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.
Depending on your DBMS, you will need to change your project setup accordingly; modify the content of
core/src/main/resources/persistence.properties
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 logback.sql=postgresql.sql
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
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 logback.sql=mysql.sql
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
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 #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 logback.sql=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
You will also need to
create directory
core/src/main/resources/META-INF
- download Oracle mapping file for the version you are building (1.1.X, 1.0.X)
rename it to
orm.xml
and copy it under the directory created above
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 logback.sql=sqlserver.sql
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
create directory
core/src/main/resources/META-INF
- download MS SQL Server mapping file for the version you are building (1.1.X, 1.0.X)
rename it to
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
.
Debian / Ubuntu warning
If you have installed Apache Tomcat 7 via Debian / Ubuntu package, you will also need to
- download the Tomcat JDBC Connection Pool JAR from Maven central repository, same version of the installed Tomcat 7
- 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).
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 -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 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="20000" removeAbandoned="true" logAbandoned="true" suspectTimeout="20000" 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.
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
<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
<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)"/>
Syncope >= 1.2.0
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
Version warning
This paragraph only applies to Apache Syncope <= 1.0.5.
Download this file and copy it under
console/src/main/webapp/WEB-INF
.
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>
assuming that you have defined a DataSource with JNDI name 'java:/syncopeDataSource' in JBoss configuration.
core jboss-deployment-structure
Add
<module name="com.mysql"/>
right before
</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
classpath*:/*Context.xml
to
/WEB-INF/classes/*Context.xml
at the beginning of core/src/main/webapp/WEB-INF/web.xml
.
Update core weblogic.xml
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.
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
Once 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
, and change development
to deployment
as in the following configuration fragment (from 1.1 onwards you will have to explicitly add this):
<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
mvn clean package -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.
Test your installation
- Point your favorite browser to administration console at http://localhost:9080/syncope-console/ (assuming that your JEE container is running on localhost, port 9080)
- Login as 'admin' / 'password'