Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Readme #1156

Merged
merged 1 commit into from
Aug 3, 2021
Merged

Update Readme #1156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions Apromore-Boot/src/main/resources/application-dev.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@

spring.datasource.password=password
spring.datasource.url=jdbc:h2:mem:Manager-Repository;DATABASE_TO_UPPER=FALSE;DB_CLOSE_DELAY=-1
spring.datasource.username=apromore
spring.jpa.hibernate.ddl-auto=none
spring.jpa.hibernate.naming.implicit-strategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyJpaImpl
spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
spring.liquibase.change-log=classpath:db/migration/changeLog.yaml
spring.liquibase.contexts=H2
spring.liquibase.password=password
spring.liquibase.user=apromore
106 changes: 23 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ If you are looking for the commercial edition (Apromore Enterprise Edition), che
* Linux Ubuntu 20.04 (We do not support newer versions as it may lead to dependency issues), Windows 10/WS2016/WS2019, Mac OSX 10.8 or newer.
* Java SE 11 ["Server JRE"](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) or
["JDK 11"](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) . For Ubuntu, it can be installed as `sudo apt install openjdk-11-jdk`
Note that newer versions, including Java SE 11, are currently not supported
* [Apache Maven](https://maven.apache.org/download.cgi) 3.5.2 or newer, and internet access for it to download this project's dependencies.
* [Lessc](http://lesscss.org/usage/) 3.9.0 or newer

* Gradlew Wrapper, included in the source code. It will download automatically on use of gradlew wrapper command.
* (optional) [MySQL server](https://dev.mysql.com/downloads/mysql/) 8.0.
* <b>Note:</b> These instructions are tested with Linux Ubuntu 20.04. With minor adaptations, these instructions may be used for Windows 10/WS20016/WS2019 and macOS 10.8 or newer.

Expand All @@ -25,18 +25,15 @@ If you are looking for the commercial edition (Apromore Enterprise Edition), che
* Check out the source code using git: `git clone https://github.com/apromore/ApromoreCore.git`
* Switch to the ApromoreCore directory: `cd ApromoreCore`
* Check out the desired branch or tag: `git checkout development`
* Execute `mvn clean install` to compile the source code into executable bundles.
* Execute `core-assemblies/apromore-core/target/assembly/bin/karaf` to start the server.
<b>Note:</b> If you deploy to port 80 (or another port below 1024), you will need to run the previous command as sudo.
* Execute `./gradlew bu bR --args='--spring.profiles.active=dev'` to compile the source code and run the project using in memory database.
* Browse [(http://localhost:8181/)](http://localhost:8181/). Login as an administrator by using the following credentials: username - "admin" and password - "password". You can also create a new account. Once logged in, a user can change their password via `Account -> Change password` menu.
* Keep the prompt/terminal window open. Ctrl-D on the window will shut the server down.
* Keep the prompt/terminal window open. Ctrl-C on the window will shut the server down.


## Configuration
The following configuration options apply to all editions of Apromore.
When there are additional configurations specific to a particular edition, they are documented in that edition's own README file.

Almost all configuration occurs in the `site.properties` file which is located in the `ApromoreCore` directory.
Almost all configuration occurs in the `application.properties` file which is located in the `ApromoreCore/Apromore-Boot/src/main/resources` directory.
The default version of this file from a fresh git checkout contains reasonable defaults that allow the server to be started without any manual configuration.


Expand All @@ -52,17 +49,16 @@ By default, Apromore Core uses MySQL database. For casual evaluation, Apromore c
mysql -u root -p
CREATE DATABASE apromore CHARACTER SET utf8 COLLATE utf8_general_ci;

CREATE USER 'apromore'@'localhost' IDENTIFIED BY 'MAcri';
GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES, EXECUTE, SHOW VIEW ON apromore.* TO 'apromore'@'localhost';
CREATE USER 'apromore'@'%' IDENTIFIED BY 'Apromore#!dev';
GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES, EXECUTE, SHOW VIEW ON apromore.* TO 'apromore'@'%';

CREATE USER 'liquibase_user'@'%' IDENTIFIED BY '7fHJV41fpJ';
CREATE USER 'liquibase_user'@'%' IDENTIFIED BY 'Apromore#!dev';
GRANT ALL PRIVILEGES ON apromore.* TO 'liquibase_user'@'%';

```

* Rebuild the server using `mvn clean install -pl :apromore-core`, or simply copy the edited `site.properties` to `core-assemblies/apromore-core/target/assembly/etc/site.cfg`.
* Identically to the default MySQL database, the H2 database will have one user: "admin".
* To use H2, edit the top-level `site.properties` file, replacing the MySQL declarations in "Database and JPA" with the commented-out H2 properties.
* Verify the database configuration in application.poperties file in directory 'ApromoreCore/Apromore-Boot/src/main/resources/application.properties'
* Execute `./gradlew bu bR` to compile the source code and run the project using MYSQL database.


### Heap size
Expand All @@ -74,21 +70,19 @@ On Windows:

```dos
set "JAVA_OPTS= -server -Xms20g -Xmx20g"
core-assemblies\apromore-core\target\assembly\bin\karaf.bat clean
```

On unix-style systems:

```bash
export JAVA_OPTS="-server -Xms20g -Xmx20g"
core-assemblies/apromore-core/target/assembly/bin/karaf clean
```


### Cache size
Apromore uses [Ehcache](https://www.ehcache.org/) for internal caching, which uses an XML configuration file.
The default in a deployed server is that the `ehcache.xml` configuration file is located at `core-assemblies/apromore-core/target/assembly/etc/ehcache.xml`.
The manager.ehcache.config.url property in site.properties can be used to point to an `ehcache.xml` at a URL of your choice.
The default in a deployed server is that the `ehcache.xml` configuration file is located at `ApromoreCore/ApromoreBoot/src/main/resoiurces`.
The manager.ehcache.config.url property in application.properties can be used to point to an `ehcache.xml` at a URL of your choice.


### Backup and restore
Expand Down Expand Up @@ -116,89 +110,35 @@ mysql --max_allowed_packet=1G --user=root -p -h localhost apromore < backup.sql
* For the event logs directory, it is recommended to zip the directory before copying it across


### LDAP setup

As distributed, Apromore maintains its own catalogue of users and passwords.
It can be configured to instead allow login based on an external LDAP directory.

* Edit the portal Spring configuration in `core-assemblies/apromore-core/target/assembly/etc/configuration/portalContext-security.xml`, uncommenting the jaasAuthenticationProvider as so:

```xml
<!-- The remote authentication details -->
<authentication-manager id="authenticationManager">
<authentication-provider ref="jaasAuthenticationProvider"/>
<authentication-provider ref="remoteAuthenticationProvider"/>
<authentication-provider ref="rememberMeAuthenticationProvider"/>
</authentication-manager>

<!-- Uncommenting this bean and adding it to #authenticationManager (above) will enable LDAP logins.
See https://docs.spring.io/spring-security/site/docs/3.1.x/reference/jaas.html -->
<beans:bean id="jaasAuthenticationProvider" class="org.springframework.security.authentication.jaas.JaasAuthenticationProvider">
<beans:property name="loginConfig" value="file:etc/login.conf"/>
<beans:property name="loginContextName" value="apromore"/>
<beans:property name="callbackHandlers">
<beans:list>
<beans:bean class="org.springframework.security.authentication.jaas.JaasNameCallbackHandler"/>
<beans:bean class="org.springframework.security.authentication.jaas.JaasPasswordCallbackHandler"/>
</beans:list>
</beans:property>
<beans:property name="authorityGranters">
<beans:list>
<beans:bean class="org.apromore.security.AuthorityGranterImpl">
<beans:property name="principalClassName" value="com.sun.security.auth.UserPrincipal"/>
<beans:property name="grants">
<beans:set>
<beans:value>ROLE_USER</beans:value>
</beans:set>
</beans:property>
</beans:bean>
</beans:list>
</beans:property>
</beans:bean>
```

* Edit `core-assemblies/apromore-core/target/assembly/etc/site.cfg` (section marked "LDAP")
* Create `core-assemblies/apromore-core/target/assembly/etc/login.conf` to match your local LDAP installation.
You could place it at another location by changing the loginConfig property from the previous step.
As an example, the UoM version looks like this:
```
apromore {
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldaps://centaur.unimelb.edu.au"
authIdentity="uid={USERNAME},ou=people,o=unimelb";
};
```
### KeyCloak setup

When the server starts with the reconfigured portal, it will automatically create new accounts for valid LDAP logins.
* Apromore supports keycloak as authentication broker which acts as IDP provider.
* You can configure your own keycloak instance with SAML,IDP,LDAP authentication.
* Once done edit the application.properties with relevant information (keycloak. prefix) that you get from keycloak.
* Apromore will use keycloak for authentication.


## Change Port Number (optional)
* Change the default port number by changing the value of `site.port` variable in the `site.cfg` file and the `org.osgi.service.http.port` variable in the `org.ops4j.pax.web.cfg` file, both present in the `core-assemblies/apromore-core/target/assembly/etc` directory.
* Change the default port number by changing the value of `server.port` variable in the `application.properties` file .
* Or `./gradlew bR --args='--server.port=8282'` to run on port 8282 as an example.

### Share file to all users (optional)

* By default Apromore does not allow you to share a file with all users (i.e. the "public" group is not supported by default). You can change this by editing the site.cfg file present in the `core-assemblies/apromore-core/target/assembly/etc` directory. Specifically, to enable the option to share files and folders with the “public” group, you should set `security.publish.enable = true` in the site.cfg file.
* By default Apromore does not allow you to share a file with all users (i.e. the "public" group is not supported by default). You can change this by editing the application.properties file present . Specifically, to enable the option to share files and folders with the “public” group, you should set `security.publish.enable = true` in the application.properties file.


## Common problems

> Out of memory while building.

* Either invoke `mvn` as `mvn -Xmx1G -XX:MaxPermSize=256m` or set the system property `MAVEN_OPTS` to `-Xmx1G -XX:MaxPermSize=256m`

> Server fails to start.

* If Apromore is configured to use MySQL, confirm that the database server is running.
* If you already run another server (e.g. OS X Server) you may need to change the port number.

> Web pages are illegible.

* Double-check that `lessc` is correctly installed. Confirm that `mvn clean install -pl :ui-theme-compact` reports no errors.

> Can't view models by clicking them in the summary list.

* Model diagrams are opened in new tabs/windows; you may need to disable popup blocking for Apromore in your browser settings.

> Where is the server log?

* `core-assemblies/apromore-core/target/assembly/data/log/karaf.log`
* Check the logging file location in application.properties. The field 'logging.file.name'
* Default location is '${user_home}/.apromore/logs/apromore.log'