Merged in feature/docker-docs (pull request #7)

Add docker instructions and minor docs additions

* Add docker folder with docs and docker-compose
Add troubleshooting and docker sections to main README

Approved-by: Paulo Veiga

README.md

@@ -27,6 +27,10 @@ The full compilation of the project can be performed executing within <project-d
 
 Once this command is execute, the file <project-dir>/wise-webapp/target/wisemapping*.war will be generated.
 
+### Compiling and running with docker-compose
+
+Check out the [docker section](./docker/README.md)
+
 ### Testing
 The previously generated war can be deployed locally executing within the directory <project-dir>/wise-webapp the following command:
 
@@ -49,6 +53,22 @@ To test the javascript frontend you then do:
 
 Now open a browser using the URL http://localhost:8000/wise-editor/src/main/webapp/
 
+## Troubleshooting
+
+<details>
+    <summary>
+    <code>mvn package</code> fails with the error <code>java.lang.UnsatisfiedLinkError: Can't load library: /usr/lib/jvm/java-11-openjdk-amd64/lib/libawt_xawt.so</code> in Ubuntu
+    </summary>
+
+    Make sure you have the jdk installed: `sudo apt-get install openjdk-11-jdk`
+</details>
+
+<details>
+    <summary><code>mvn package</code> does not generate the wisemapping.war file </summary>
+
+    Run `mvn clean install -DskipTests`
+</details>
+
 ## Maintenance
 
 

docker/README.md

@@ -0,0 +1,84 @@
+This is an approach to compiling and installing wisemapping using docker and docker-compose.
+
+In this way you can run the app without installing specific java, maven, tomcat and mysql versions in the host machine just for this project.
+
+# Prerequisites
+
+Make sure you have [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) installed. You might also want to [run docker without sudo](https://docs.docker.com/engine/install/linux-postinstall/) if you are on linux.
+
+# Compile wisemapping using docker
+
+This is not required to run the app using docker. You might skip this section if you already have the `war` file or if you want to compile it by yourself.
+
+We create a volume so the downloaded packages can be reused across different containers (a new container is created each time we run the image). This is run only once.
+
+```
+docker volume create --name maven-repo-wisemapping
+```
+
+Then we can run the following command from the project root:
+
+```
+docker run -it --rm --name wisemapping-compile \
+  -v maven-repo-wisemapping:/root/.m2 \
+  -v "$(pwd)":/usr/src/mymaven -w /usr/src/mymaven maven:3-jdk-11 \
+  mvn clean install -DskipTests
+```
+
+After that, you can find the result of the compilation in `wise-webapp/target/wisemapping.war`.
+
+# Run using docker-compose
+
+## Edit config
+
+### app.properties
+
+First of all, edit your `wise-webapp/src/main/webapp/WEB-INF/app.properties` to configure the app to use mysql.
+
+- Uncomment the `MySQL 5.X configuration properties` section
+- Change the `database.url` line to this: `database.url=jdbc:mysql://db/wisemapping?useUnicode=yes&characterEncoding=UTF-8` (the host is "db" instead of "localhost")
+- Change the default username and password
+- Comment the `HSQL Configuration properties` section
+
+> Any time you make any config modification, you will have to re-compile the project, using the docker build shown before or any other method.
+
+### docker-compose.yml
+
+Review the `docker-compose.yml` file and edit it with your settings.
+In the example provided the important bits are:
+
+- `/opt/wisemapping-db`: this is where the mysql database files will be stored in your machine.
+- Change the default password for the database to match your app.properties password. Please don't keep "password"!
+- You might want to remove the `ports:` section in the db service if you don't want your db exposed to the outside.
+
+```
+ports:
+  - 3306:3306
+```
+
+- You might want to change the port mapping for web (by default it will run in port 8082)
+
+```
+ports:
+  - "8082:8080"
+```
+
+- Change `../wise-webapp/target/wisemapping.war` if you want to store the war file anywhere else in your machine. If you leave the default, the war file deployed will be overriden each time you build the app. You might not want that behavior.
+
+## Running
+
+Once the configs are ready, from this folder, run `docker-compose -p wise-webapp up -d` to run the web and the database containers as daemons. They will start automatically whith the machine.
+
+You can check your docker running containers with `docker ps`.
+
+To stop them you can run `docker-compose down` from this directory (doing this, they won't start automatically anymore).
+
+Check out docker and docker-compose docs for more container management utilities.
+
+## Areas for improvement
+
+- Create a Dockerfile to build wise-webapp using an `app.properties` file mounted from this directory (make building easier).
+- Simplify this documentation, simplify the process
+- Allow to pass configuration as environment variables form docker-compose
+
+If any of this can be improved, please submit a patch or issue.

docker/docker-compose.yml

@@ -0,0 +1,24 @@
+version: "3.3"
+services:
+  db:
+    image: mysql:5.5
+    volumes:
+      - /opt/wisemapping-db:/var/lib/mysql
+      - ./mysql-init/:/docker-entrypoint-initdb.d
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: wisemapping
+      MYSQL_USER: wisemapping
+      MYSQL_PASSWORD: password
+    ports:
+      - 3306:3306
+    restart: unless-stopped
+  web:
+    depends_on:
+      - db
+    image: tomcat:9
+    volumes:
+      - ../wise-webapp/target/wisemapping.war:/usr/local/tomcat/webapps/ROOT.war
+    ports:
+      - "8082:8080"
+    restart: unless-stopped

docker/mysql-init/0001create-database.sql

@@ -0,0 +1,10 @@
+#
+# Command: mysql -u root -p < create_database.sql
+#
+DROP DATABASE IF EXISTS wisemapping;
+
+CREATE DATABASE IF NOT EXISTS wisemapping
+  CHARACTER SET = 'utf8'
+  COLLATE = 'utf8_unicode_ci';
+GRANT ALL ON wisemapping.* TO 'wisemapping'@'localhost';
+SET PASSWORD FOR 'wisemapping'@'localhost' = PASSWORD('password');

docker/mysql-init/0002create-schemas.sql

@@ -0,0 +1,137 @@
+#
+# Command: mysql -u root -p < create_schemas.sql
+#
+
+USE wisemapping;
+
+CREATE TABLE COLLABORATOR (
+  id            INTEGER            NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  email         VARCHAR(255)
+                CHARACTER SET utf8 NOT NULL UNIQUE,
+  creation_date DATE
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE USER (
+  colaborator_id   INTEGER            NOT NULL PRIMARY KEY,
+  authentication_type CHAR(1)
+                      CHARACTER SET utf8 NOT NULL,
+  authenticator_uri   VARCHAR(255)
+                      CHARACTER SET utf8,
+  firstname        VARCHAR(255) CHARACTER SET utf8 NOT NULL,
+  lastname         VARCHAR(255) CHARACTER SET utf8 NOT NULL,
+  password         VARCHAR(255) CHARACTER SET utf8 NOT NULL,
+  activation_code  BIGINT(20)         NOT NULL,
+  activation_date  DATE,
+  allow_send_email CHAR(1) CHARACTER SET utf8 NOT NULL DEFAULT 0,
+  locale           VARCHAR(5),
+  FOREIGN KEY (colaborator_id) REFERENCES COLLABORATOR (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE MINDMAP (
+  id             INTEGER            NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  title          VARCHAR(255)
+                 CHARACTER SET utf8 NOT NULL,
+  description    VARCHAR(255)
+                 CHARACTER SET utf8 NOT NULL,
+  xml            MEDIUMBLOB         NOT NULL,
+  public         BOOL               NOT NULL DEFAULT 0,
+  creation_date  DATETIME,
+  edition_date   DATETIME,
+  creator_id     INTEGER            NOT NULL,
+  tags           VARCHAR(1014)
+                 CHARACTER SET utf8,
+  last_editor_id INTEGER            NOT NULL,
+  FOREIGN KEY (creator_id) REFERENCES USER (colaborator_id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE LABEL (
+  id              INTEGER            NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  title           VARCHAR(30)
+                  CHARACTER SET utf8 NOT NULL,
+  creator_id      INTEGER            NOT NULL,
+  parent_label_id INTEGER,
+  color           VARCHAR(7)         NOT NULL,
+  iconName        VARCHAR(50)       NOT NULL,
+  FOREIGN KEY (creator_id) REFERENCES USER (colaborator_id),
+  FOREIGN KEY (parent_label_id) REFERENCES LABEL (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE R_LABEL_MINDMAP (
+  mindmap_id       INTEGER            NOT NULL,
+  label_id         INTEGER            NOT NULL,
+  PRIMARY KEY (mindmap_id, label_id),
+  FOREIGN KEY (mindmap_id) REFERENCES MINDMAP (id),
+  FOREIGN KEY (label_id) REFERENCES LABEL (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE MINDMAP_HISTORY
+(id            INTEGER    NOT NULL PRIMARY KEY AUTO_INCREMENT,
+ xml           MEDIUMBLOB NOT NULL,
+ mindmap_id    INTEGER    NOT NULL,
+ creation_date DATETIME,
+ editor_id     INTEGER    NOT NULL,
+  FOREIGN KEY (mindmap_id) REFERENCES MINDMAP (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE COLLABORATION_PROPERTIES (
+  id                 INTEGER NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  starred            BOOL    NOT NULL DEFAULT 0,
+  mindmap_properties VARCHAR(512)
+                     CHARACTER SET utf8
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE COLLABORATION (
+  id             INTEGER NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  colaborator_id INTEGER NOT NULL,
+  properties_id  INTEGER NOT NULL,
+  mindmap_id     INTEGER NOT NULL,
+  role_id        INTEGER NOT NULL,
+  FOREIGN KEY (colaborator_id) REFERENCES COLLABORATOR (id),
+  FOREIGN KEY (mindmap_id) REFERENCES MINDMAP (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION,
+  FOREIGN KEY (properties_id) REFERENCES COLLABORATION_PROPERTIES (id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE TAG (
+  id      INTEGER            NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  name    VARCHAR(255)
+          CHARACTER SET utf8 NOT NULL,
+  user_id INTEGER            NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES USER (colaborator_id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+CREATE TABLE ACCESS_AUDITORY (
+  id         INTEGER NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  login_date DATE,
+  user_id    INTEGER NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES USER (colaborator_id)
+    ON DELETE CASCADE
+    ON UPDATE NO ACTION
+)
+  CHARACTER SET utf8;
+
+COMMIT;

docker/mysql-init/0003apopulate-schemas.sql

@@ -0,0 +1,13 @@
+#
+# Command: mysql -u root -p < apopulate_schemas.sql
+#
+
+INSERT INTO COLLABORATOR (id, email, creation_date) VALUES (1, 'test@wisemapping.org', CURRENT_DATE());
+INSERT INTO USER (colaborator_id, firstname, lastname, password, activation_code, activation_date, allow_send_email,authentication_type)
+  VALUES (1, 'Test', 'User', 'ENC:a94a8fe5ccb19ba61c4c0873d391e987982fbbd3', 1237, CURRENT_DATE(), 1,'D');
+
+INSERT INTO COLLABORATOR (id, email, creation_date) VALUES (2, 'admin@wisemapping.org', CURRENT_DATE());
+INSERT INTO USER (colaborator_id, firstname, lastname, password, activation_code, activation_date, allow_send_email,authentication_type)
+  VALUES (2, 'Admin', 'User', 'ENC:a94a8fe5ccb19ba61c4c0873d391e987982fbbd3', 1237, CURRENT_DATE(), 1,'D');
+
+COMMIT;