Installation

Posted on Aug 06, 2017 by webmaster

This page explain how to install the Project Web Manager using the WAR release bundle.

In order to make the application work you'll need two mandatory things:

  • A Java 8 virtual machine
  • A data base (MySQL or MariaDB only for now)
  • A Java Application Web Server, such as Tomcat 8.x or whatever supporting Java Servlet v3.1

If you want better performances, you can complete the installation using an HTTP Web server (Apache or IIS).

Since this is a J2EE application, it can work on Windows or Unix.

 Download

Upgrade/Migration

Posted on Aug 06, 2017 by webmaster

If you already have a working copy of PWM, read the upgrade documentation.

The Data Base

Posted on Jan 06st, 2014 by webmaster

For now, the only data base that is supported is MySQL and MariaDB. The project may not work on other data base due to specific SQL request, we'll keep you informed of any changes.

  • Download MySQL or MariaDB data base
  • Install the data base following the instructions regarding your environment (Windows or Unix)
  • Set a root password to your data base (up to you to define the root login and password)
  • Start your data base server (depending of your environment)
  • Prepare the database (commands are the same for MySQL and MariaDB):
    • Connect to the data base, in a console type:
      mysql -u root -p
      press enter, where root is the login of the root user of your data base (selected during the database installation).
    • MySQL will prompt you for the root password, type it.
    • Use the following code to create a database:
      create database IF NOT EXISTS project_m CHARACTER SET=UTF8;
      press enter toexecute the request.
    • Use the following request to add a user in your data base that will be the root user of Project Web Manager:
      CREATE USER pwmroot IDENTIFIED BY 'yourPasswordForThisUser';
      press enter to execute the request.
      Where yourPasswordForThisUser is a secret password of yourchoice (don't loose it, you'll need it later).
    • Give pwmroot all rights on the project_m databse using the following request:
      GRANT ALL PRIVILEGES ON project_m.* TO 'pwmroot'@'localhost' IDENTIFIED BY 'yourPasswordForThisUser';FLUSH PRIVILEGES;
      press enter to execute the two requests.
      Those lines will grand access only if already connected to the computer holding the data base, you can change and complete if needed.
    • Exit the connexion as root, and reconnect as pwmroot:
      exit
      press enter to execute
      mysql -u pwmroot -p
      press enter and give the password for the pwmroot user.
    • Run the following commands that will create all tables and index used by Project Web Manager (execute as pwmroot user in a mysql session):
      source path/mysql-create.sql
      where path is the path to the script (ex: c:/toto/titi), press enter to execute.
      Note It may be necessary before loading the script to specify the targeted data base, in order to do so, simply use the following command:
      USE project_m;
      CAUTION whatever your platform is use '/' (and NOT '\'), and do not use spaces in the path, move the file if needed.
    • Exit the connexion:
      exit
      press enter to execute.

The data base is in place, in order to let people upload large file into it you'll need to change/add one line in your mysql data base configuration file.

Note that in PWM, each file can do 2Mg and you can post a maximum of 16M of files at the same time.

  • Stop your MySQL server (depending of your environment)
  • Find your data base configuration file (called myxxxxx.ini on Windows or myxxxx.cfg, or myxxxx.cnf on Unix). Note that xxxx can be nothing or whatever you define as your MySQL server/instance.
  • Edit the file using your favourite editor.
  • Add or change in section [mysqld]
    max_allowed_packet=20M
  • Add or change in section [mysqldump]
    max_allowed_packet=20M
  • Save the file, and restart your MySQL server.

If you understand what you're doing you can also change other parameters for your MySQL server.

Do NOT forget to Re-Start your MySQL server.

The Java Application Web Server

Posted on Aug 06, 2017 by webmaster

As all J2EE application, you'll need a Java Application Web Server. In our cases, the only mandatory need is to support Servlet version 3.1 (read the documentation of your server for more details).

The following explanations show how to configure a Tomcat server

  • Download Tomcat (v8.x minimum) (choose the version depending of you system)
  • Unzip or install the downloaded file.
  • If you like, you can install APR libs for your Tomcat (https://tomcat.apache.org/native-doc/index.html)
  • Copy the following Jar to your Tomcat/lib directory regarding the targeted data base (stop it first if started):
    • For MySQL : mysql-connector-java-5.x.y-bin.jar downloadable here Please use the Platform Independent download.
    • For MariaDB : mariadb-java-client-2.x.x.jar downloadable here Select the JAR file for download.

Application Itself

Posted on Aug 06, 2017 by webmaster

Before starting the application, you'll need to:
  • set the data base access properly
  • configure the Spring mail service
  • configure the Spring temporary file service
  • configure the Spring super administrator service
  • configure the logs

Regarding the data base access:
  • Open the WAR file using a Zip program (such as 7-Zip for Windows or whatever tool you want)
  • Edit the file in META-INF directory called context.xml
  • In the file, you can change the login/password and database name
  • Change the login and password to match what you have done during the data base installation.
    ...
    username="pwmroot"
    password="yourPasswordForThisUser"
    ... />
  • If your data base is MySQL:
    ...
    driverClassName="com.mysql.jdbc.Driver"
    ... />
  • If your data base is MariaDB:
    ...
    driverClassName="org.mariadb.jdbc.Driver"
    ... />
  • Save your changes

Regarding the mail service configuration:
  • Open the WAR file using a Zip program (such as 7-Zip for Windows or whatever tool you want)
  • Open the file WEB-INF\lib\pwm.core-x.x.xx.jar
  • Edit the file in spring directory called services.properties
  • If you are using mail forwarding on your server, there is nothing to do, otherwise simply specify the following informations:
    • serverName will represent the name of the mail server, can be an IP or a DNS name
    • login will represent a login to use with the mail server if needed
    • password will represent a password to use with the mail server if needed
    • port will represent the mail server port
    • ssl indicate true if you want to use SSL
  • Save your changes

Regarding the temporary file service configuration:
  • Open the WAR file using a Zip program (such as 7-Zip for Windows or whatever tool you want)
  • Open the file WEB-INF\lib\pwm.core-x.x.xx.jar
  • Edit the file in spring directory called services.properties
  • Property name is temporary.directory
  • Save your changes

Regarding the super user service configuration:
  • Open the WAR file using a Zip program (such as 7-Zip for Windows or whatever tool you want)
  • Open the file WEB-INF\lib\pwm.core-x.x.xx.jar
  • Edit the file in spring directory called services.properties
  • You'll need to specify a login and a password for the super user administration console. This console is a mono user interface used for the creation of domain. You'll connect to it at next step.
  • Properties name are : super.admin.login and super.admin.password
  • Save your changes. You can use whatever you want as login and password but you must set a login and a password.

Regarding the log configuration:
  • Open the WAR file using a Zip program (such as 7-Zip for Windows or whatever tool you want)
  • Edit the file in WEB-INF\classes\ directory called log4j2.xml
  • At least, you'll need to change the log path.
    ... <RollingRandomAccessFile name="localFile" fileName="${sys:catalina.base}/logs/web_${log_localFile}" filePattern="${sys:catalina.base}/logs/web_${log_localFile}-%d{yyyy-MM-dd}" append="true"> <PatternLayout pattern="%-20X{ipAddress} %-5X{userId}/%-3X{userDomain} [%d{dd/MM/yyyy HH:mm:ss}] - %5p - %35c{1} - %m %n" /> <Policies> <TimeBasedTriggeringPolicy /> <SizeBasedTriggeringPolicy size="10 MB" /> </Policies> <DefaultRolloverStrategy max="20" /> </RollingRandomAccessFile> ...
  • Save your changes. You can also change the mail configuration (remove it or change it).

Run The Application

Posted on Aug 06, 2017 by webmaster

Now is the time to deploy you WAR with the configuration of your choice.

Stop your application server.

Simply copy the WAR file in your server deployment directory (on Tomcat it is the webapps directory).

Start your application server.

Have a look at your logs, if no error login to the super user console: https://localhost:8080/pwm/

Use your login/password set for the super user service (super.admin.login and super.admin.password).

Click on the golden key.

Create a domain by specifying the first administrator user and the license options. A user will be created and an email will be send with its login/password information.

Use 0 for the domain key.

Note the login and password you've entered in order to remenber it later.

Quit the super user console (use the plug near the golden key).

Have a look at your logs, if no error login using the main application: https://localhost:8080/pwm/ and use the login password you've just entered in order to login as a domain administrator.