[SYNCOPE-1256] Site review + getting started
authorFrancesco Chicchiriccò <ilgrosso@apache.org>
Mon, 25 Jun 2018 11:06:44 +0000 (13:06 +0200)
committerFrancesco Chicchiriccò <ilgrosso@apache.org>
Mon, 25 Jun 2018 11:09:30 +0000 (13:09 +0200)
12 files changed:
client/console/src/main/java/org/apache/syncope/client/console/chartjs/Pie.java [new file with mode: 0644]
client/console/src/main/java/org/apache/syncope/client/console/chartjs/PieChartData.java [new file with mode: 0644]
src/main/asciidoc/getting-started/obtain.adoc
src/main/asciidoc/reference-guide/concepts/extensions.adoc
src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc
src/site/xdoc/building.xml
src/site/xdoc/contributing.xml
src/site/xdoc/docs/index.xml
src/site/xdoc/downloads.xml
src/site/xdoc/index.xml
src/site/xdoc/release-process.xml
src/site/xdoc/source-repository.xml

diff --git a/client/console/src/main/java/org/apache/syncope/client/console/chartjs/Pie.java b/client/console/src/main/java/org/apache/syncope/client/console/chartjs/Pie.java
new file mode 100644 (file)
index 0000000..94e971e
--- /dev/null
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.syncope.client.console.chartjs;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Provides a simple implementation of chart.js pie chart.
+ *
+ * @see <a href="http://www.chartjs.org/docs/#pieChart">chart.js docs</a>
+ */
+public class Pie extends SimpleChart<PieChartData, PieChartOptions> implements Serializable {
+
+    private static final long serialVersionUID = -6898362145345731457L;
+
+    @Override
+    public PieChartOptions getOptions() {
+        if (options == null) {
+            options = new PieChartOptions();
+        }
+        return options;
+    }
+
+    @Override
+    public List<PieChartData> getData() {
+        if (data == null) {
+            data = new ArrayList<>();
+        }
+        return data;
+    }
+}
diff --git a/client/console/src/main/java/org/apache/syncope/client/console/chartjs/PieChartData.java b/client/console/src/main/java/org/apache/syncope/client/console/chartjs/PieChartData.java
new file mode 100644 (file)
index 0000000..eb941ae
--- /dev/null
@@ -0,0 +1,52 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.syncope.client.console.chartjs;
+
+/**
+ * Provides chart data used by pie charts.
+ */
+public class PieChartData extends SimpleColorValueChartData {
+
+    private static final long serialVersionUID = -5122104387810776812L;
+
+    private String label;
+
+    /**
+     * Instantiates a new pie chart data.
+     *
+     * @param value the value
+     * @param color the color
+     */
+    public PieChartData(final Number value, final String color) {
+        super(value, color);
+    }
+
+    public PieChartData(final Number value, final String color, final String label) {
+        super(value, color);
+        this.label = label;
+    }
+
+    public String getLabel() {
+        return label;
+    }
+
+    public void setLabel(final String label) {
+        this.label = label;
+    }
+}
index 87d540a..be92fac 100644 (file)
@@ -286,6 +286,148 @@ Credentials: `admin` / `password`
 
 |===
 
+=== Docker
+
+https://www.docker.com/[Docker^] images ready to use, published to https://hub.docker.com[Docker Hub^].
+
+[CAUTION]
+.Target Audience
+Getting up and running quickly on Docker. +
+*All configurations available to set, difficult customizations.*
+
+[WARNING]
+Working with these images requires to have Docker correctly installed and configured.
+
+[TIP]
+The Docker images can be used with orchestration tools as
+https://docs.docker.com/compose/[Docker Compose^] or https://kubernetes.io/[Kubernetes^].
+
+==== Docker images
+
+===== Core
+
+Apache Syncope Core, see <<a-bird-s-eye-view-on-the-architecture,above>> for information.
+
+Port exposed: `8080`.
+
+Environment variables:
+
+* `DBMS`: which type of relational DBMS is to be used as internal storage for Syncope Core; valid values are
+`postgresql`, `mariadb`, `mssql`, `mysql`
+* `DB_URL`: JDBC URL of internal storage
+* `DB_USER`: username for internal storage authentication
+* `DB_PASSWORD`: password for internal storage authentication
+* `DB_POOL_MAX`: internal storage connection pool: ceiling
+* `DB_POOL_MIN`: internal storage connection pool: floor
+* `OPENJPA_REMOTE_COMMIT`: configure multiple instances, with high availability; valid values are the ones accepted by
+OpenJPA for
+http://openjpa.apache.org/builds/3.0.0/apache-openjpa/docs/ref_guide_event.html[remote event notification^] including
+`sjvm` (single instance)
+
+===== Console
+
+Apache Syncope Admin UI, see <<a-bird-s-eye-view-on-the-architecture,above>> for information.
+
+Port exposed: `8080`.
+
+Environment variables:
+
+* `CORE_SCHEME`: URL scheme to connect to Syncope Core; valid values are `http` or `https`
+* `CORE_HOST`: host name or IP address to connect to Syncope Core
+* `CORE_PORT`: port number to connect to Syncope Core
+
+===== Enduser
+
+Apache Syncope Enduser UI, see <<a-bird-s-eye-view-on-the-architecture,above>> for information.
+
+Port exposed: `8080`.
+
+Environment variables:
+
+* `CORE_SCHEME`: URL scheme to connect to Syncope Core; valid values are `http` or `https`
+* `CORE_HOST`: host name or IP address to connect to Syncope Core
+* `CORE_PORT`: port number to connect to Syncope Core
+
+==== Docker Compose samples
+
+Besides the one reported below, more samples are
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/tree/syncope-{docVersion}/docker/src/main/resources[available^].
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/tree/master/docker/src/main/resources[available^].
+endif::[]
+
+.Syncope Core, Admin UI and Enduser UI with PostgreSQL
+====
+The `docker-compose.yml` below will create and connect 4 Docker containers to provide a full-fledged, single
+instance, Apache Syncope deployment. All referenced images are available on Docker Hub.
+
+[source,yaml,subs="verbatim,attributes"]
+----
+version: '3.3'
+
+services:
+   db: // <1>
+     image: crunchydata/crunchy-postgres:centos7-10.3-1.8.2
+     restart: always
+     environment:
+       PG_ROOT_PASSWORD: postgres
+       PG_MODE: primary
+       PG_PRIMARY_USER: postgres
+       PG_PRIMARY_PASSWORD: postgres
+       PG_PRIMARY_HOST: localhost
+       PG_PRIMARY_PORT: 5432
+       PG_DATABASE: syncope
+       PG_USER: syncope
+       PG_PASSWORD: syncope
+
+   syncope: // <2>
+     depends_on:
+       - db
+     image: apache/syncope:{docVersion}
+     ports:
+       - "18080:8080"
+     restart: always
+     environment:
+       DBMS: postgresql
+       DB_URL: jdbc:postgresql://db:5432/syncope
+       DB_USER: syncope
+       DB_PASSWORD: syncope
+       DB_POOL_MAX: 10
+       DB_POOL_MIN: 2
+       OPENJPA_REMOTE_COMMIT: sjvm
+
+   syncope-console: // <3>
+     depends_on:
+       - syncope
+     image: apache/syncope-console:{docVersion}
+     ports:
+       - "28080:8080"
+     restart: always
+     environment:
+       CORE_SCHEME: http
+       CORE_HOST: syncope
+       CORE_PORT: 8080
+
+   syncope-enduser: // <4>
+     depends_on:
+       - syncope
+     image: apache/syncope-enduser:{docVersion}
+     ports:
+       - "38080:8080"
+     restart: always
+     environment:
+       CORE_SCHEME: http
+       CORE_HOST: syncope
+       CORE_PORT: 8080
+----
+<1> Database container for usage as internal storage, based on PostgreSQL 10.3
+<2> Apache Syncope Core, single instance, port `18080` exposed
+<3> Apache Syncope Admin UI, port `28080` exposed
+<4> Apache Syncope Enduser UI, port `38080` exposed
+====
+
 === Maven Project
 
 This is the *preferred method* for working with Apache Syncope, giving access to the whole set of customization
index 52d245e..6ece732 100644 (file)
@@ -138,7 +138,7 @@ ifeval::["{snapshotOrRelease}" == "release"]
 https://github.com/apache/syncope/tree/syncope-{docVersion}/ext/oidcclient[source tree^]
 endif::[]
 ifeval::["{snapshotOrRelease}" == "snapshot"]
-https://github.com/apache/syncope/tree/2_0_X/ext/oidcclient[source tree^]
+https://github.com/apache/syncope/tree/master/ext/oidcclient[source tree^]
 endif::[]
 .
 ====
index 0126ac6..6aee40e 100644 (file)
@@ -23,7 +23,7 @@
 
 When deploying multiple Syncope <<core>> instances with a single database or database cluster, it is of
 fundamental importance that the contained OpenJPA instances are correctly configured for
-http://ci.apache.org/projects/openjpa/trunk/docbook/ref_guide_event.html[remote event notification^]. +
+http://openjpa.apache.org/builds/3.0.0/apache-openjpa/docs/ref_guide_event.html[remote event notification^]. +
 Such configuration, in fact, allows the OpenJPA data cache to remain synchronized when deployed in multiple JVMs, thus
 enforcing data consistency across all Syncope Core instances.
 
@@ -39,7 +39,7 @@ see the OpenJPA documentation for reference.
 
 [WARNING]
 ====
-http://ci.apache.org/projects/openjpa/trunk/docbook/ref_guide_event.html[OpenJPA documentation^]'s XML
+The http://openjpa.apache.org/builds/3.0.0/apache-openjpa/docs/ref_guide_event.html[OpenJPA documentation^]'s XML
 snippets refer to a different configuration style; for example, when used in persistence.properties`, this:
 
 [source,xml]
index cef7d28..79aa05e 100644 (file)
@@ -65,6 +65,10 @@ under the License.
         To build Syncope without running any test nor check do:
         <source>$ mvn -PskipTests,all</source>
       </p>
+      <p>
+        To build Syncope without running any test nor check, but generating Docker images, do:
+        <source>$ mvn -PskipTests,all,docker</source>
+      </p>
     </section>
     
     <section name="Building documentation">
@@ -122,32 +126,25 @@ $ mvn -Pjrebel</source>
         <h4>DBMSes</h4>
 
         <h5>PostgreSQL</h5>
-        After providing connection information in <code>src/main/resources/postgres/domains/Master.properties</code>,
-        perform the full test suite against a real <a href="http://www.postgresql.org/">PostgreSQL</a> database via
+        Perform the full test suite against a real <a href="http://www.postgresql.org/">PostgreSQL</a> database via
         <source>$ mvn -Ppostgres-it</source>
 
         <h5>MySQL</h5>
-        After providing connection information in <code>src/main/resources/mysql/domains/Master.properties</code>,
-        perform the full test suite against a real <a href="http://www.mysql.com/">MySQL</a> database via
+        Perform the full test suite against a real <a href="http://www.mysql.com/">MySQL</a> database via
         <source>$ mvn -Pmysql-it</source>
 
         <h5>MariaDB</h5>
-        After providing connection information in <code>src/main/resources/mariadb/domains/Master.properties</code>,
-        perform the full test suite against a <a href="https://mariadb.org/">MariaDB</a> database via
+        Perform the full test suite against a <a href="https://mariadb.org/">MariaDB</a> database via
         <source>$ mvn -Pmariadb-it</source>
 
         <h5>Oracle database</h5>
-        After providing connection information in <code>src/main/resources/oracle/domains/Master.properties</code>
-        and having <a href="http://www.mkyong.com/maven/how-to-add-oracle-jdbc-driver-in-your-maven-local-repository/">
+        After having <a href="http://www.mkyong.com/maven/how-to-add-oracle-jdbc-driver-in-your-maven-local-repository/">
           set up the appropriate JDBC driver in your local Maven repository</a>, perform the full test suite
         against a real <a href="http://www.oracle.com/products/database/">Oracle</a> database via
         <source>$ mvn -Poracle-it</source>
 
         <h5>MS SQL Server</h5>
-        After providing connection information in <code>src/main/resources/sqlserver/domains/Master.properties</code>
-        and having <a href="http://claude.betancourt.us/add-microsoft-sql-jdbc-driver-to-maven/">
-          set up the appropriate JDBC driver in your local Maven repository</a>, perform the full test suite
-        against a real <a href="http://www.microsoft.com/sqlserver/en/us/default.aspx">MS SQL Server</a> database via
+        Prform the full test suite against a real <a href="http://www.microsoft.com/sqlserver/en/us/default.aspx">MS SQL Server</a> database via
         <source>$ mvn -Psqlserver-it</source>
 
         <h4>Java EE containers</h4>
index 788b3c3..8927527 100644 (file)
@@ -42,7 +42,7 @@ under the License.
       <subsection name="Code">
         <ul>
           <li>If you have found an issue or you want to propose a new feature, post a message to the 
-            <a href="mailing-lists.html">Syncope Dev list or jump on IRC</a> to discuss it.
+            <a href="mailing-lists">Syncope Dev list or jump on IRC</a> to discuss it.
           </li>
           <li>Search existing 
             <a href="https://issues.apache.org/jira/secure/IssueNavigator.jspa" rel="nofollow">issues</a> to see 
@@ -51,7 +51,7 @@ under the License.
           <li>If this issue was never encountered before, create a new 
             <a href="https://issues.apache.org/jira/browse/SYNCOPE">JIRA</a> issue.
           </li>
-          <li>Get the <a href="source-repository.html">source code</a></li>
+          <li>Get the <a href="source-repository">source code</a></li>
           <li>Develop / describe a test case to demonstrate the issue.</li>
           <li>Review and apply our <a href="https://cwiki.apache.org/confluence/display/SYNCOPE/Git+workflow">Git workflow</a>.</li>
         </ul>
index cf6bbdd..8cc0734 100644 (file)
@@ -36,10 +36,10 @@ under the License.
       </p>
       <p>
         If you find errors or omissions in the documentation, please don’t hesitate to 
-        <a href="../issue-tracking.html">submit an issue</a> or 
-        <a href="../contributing.html#Documentation">contribute</a>.
+        <a href="../issue-tracking">submit an issue</a> or 
+        <a href="../contributing#Documentation">contribute</a>.
         We also encourage you to ask questions and discuss any aspects of the project on the 
-        <a href="../mailing-lists.html">mailing lists or IRC</a>. New contributors are always welcome!
+        <a href="../mailing-lists">mailing lists or IRC</a>. New contributors are always welcome!
       </p>
       
       <subsection name="Guides">
index d07e3f8..44cdaca 100644 (file)
@@ -37,13 +37,14 @@ under the License.
       </p>
 
       <div class="alert alert-info">
-        <h4>Don't know which downloads best suit your needs?</h4>
+        <h4>Don't know what do download? Click the buttons below to get more information.</h4>
         <br/>
         <div class="btn-group">
           <a href="docs/getting-started.html#maven-project" class="btn">Maven Project</a>
           <a href="docs/getting-started.html#standalone" class="btn">Standalone</a>
           <a href="docs/getting-started.html#debian-packages" class="btn">Debian Packages</a>
           <a href="docs/getting-started.html#gui-installer" class="btn">GUI Installer</a>
+          <a href="docs/getting-started.html#docker" class="btn">Docker images</a>
           <a href="docs/getting-started.html#eclipse-ide-plugin" class="btn">Eclipse IDE Plugin</a>
           <a href="docs/getting-started.html#netbeans-ide-plugin" class="btn">Netbeans IDE Plugin</a>
         </div>
index f3aa6fc..0a715df 100644 (file)
@@ -50,10 +50,10 @@ under the License.
     <div class="row" style="margin-bottom: 20px;">
       <div class="col-sm-offset-5 col-sm-2 text-center">
         <div class="btn-group" data-toggle="buttons">
-          <a class="btn btn-large btn-success center-block" style="width: 250px;" href="downloads.html">I want to build my IdM with<br/>Apache Syncope</a>
+          <a class="btn btn-large btn-success center-block" style="width: 250px;" href="downloads">I want to build my IdM with<br/>Apache Syncope</a>
         </div>
         <div class="btn-group" data-toggle="buttons">
-          <a class="btn btn-large btn-info center-block" style="width: 250px;" href="contributing.html">I want to contribute to<br/>Apache Syncope</a>
+          <a class="btn btn-large btn-info center-block" style="width: 250px;" href="contributing">I want to contribute to<br/>Apache Syncope</a>
         </div>
       </div>
     </div>
index c3e5804..67b6b0f 100644 (file)
@@ -148,7 +148,7 @@ under the License.
           fundamental importance to go through these at least once for every major release.
         </p>
         <p>
-          For more information please take a look at <a href="building.html#fitcore-reference">build instructions</a>.
+          For more information please take a look at <a href="building#fitcore-reference">build instructions</a>.
         </p>
       </subsection>
       
@@ -573,6 +573,10 @@ svn mv $VERSION/* .
 svn rm $VERSION
 svn commit -m "Promoting the staging site"]]></source>
           </li>
+          <li>
+            If releasing from 2_0_X, deploy the updated Docker images to <a href="https://hub.docker.com/">DockerHub</a> by adjusting the GIT tag
+             name then running the <a href="https://builds.apache.org/job/Syncope-2_0_X-Docker"/>dedicated Jenkins job</a>.
+          </li>
         </ol>
       </subsection>
       
index bd35757..93ccb4e 100644 (file)
@@ -55,7 +55,7 @@ under the License.
     </section>
     
     <section name="Building">
-      <p>Review and apply the various <a href="building.html">build options</a>.</p>
+      <p>Review and apply the various <a href="building">build options</a>.</p>
     </section>
   </body>
 </document>