Skip to content

Setup

Setup

All the data that you import and see in Phaedra, is stored in an environment. As you launch the Phaedra application, the first thing you will see is a list of available environments. After selecting an environment - which may require a login - the environment's contents will be loaded and become accessible to you.

This document describes environments in more detail, and explains how to configure Phaedra to access multiple environments.

Single-user vs multi-user

Phaedra supports two environment modes: single-user and multi-user. While both modes may appear similar from within the application, there are several very important differences:

A single-user environment:

  • Runs locally, on your computer.
  • Has no way to share data with other users.
  • Starts up and shuts down along with the application.

A multi-user environment:

  • Runs from a central database server and file share.
  • Multiple users may be connected to the same environment simultaneously.
  • Data can be shared between users, as each protocol has a security model that grants or denies access to other users.

In most real-world scenarios, a multi-user setup will be used. However, a single-user setup still has several advantages:

  • It is a good way to get started quickly, and to get to know the application.
  • Data is still accessible in offline situations.

Environment configuration

Environments are listed and configured in a file named config.xml. In Phaedra's initialization file (phaedra.ini, located in the Phaedra top-level directory), you can refer to this configuration file using the phaedra.config system property.

For example:

-Dphaedra.config=file:///local/path/to/config.xml

Or:

-Dphaedra.config=smb://hostname/path/to/config.xml

Note: From an adminstration point of view, it is convenient to store the config.xml file on a shared (read-only) location and refer to it via an "smb://" path.

Upon launching, Phaedra will parse this configuration file and add the listed environments to its environment registry. In a new out-of-the-box installation, the system property mentioned above will be absent and only a default embedded (i.e. single-user) environment will be available.

This is what the default configuration looks like:

<config>
    <environments>
        <environment name="Embedded">
            <fs><path>./embedded.env</path></fs>
            <db><url>jdbc:h2:./embedded.env/db</url></db>
        </environment>
    </environments>
</config>

There are only 2 settings in the default configuration:

  • The fs tag contains the path to the file share, in this case a local folder named embedded.env relative to the Phaedra top-level directory.
  • The db tag contains a JDBC URL to the database instance, in this case an embedded H2 database stored in the same local folder.

A multi-user environment usually requires more configuration:

<config>
<settings>
    <setting name="pwd.path">\\path\to\pwddir</setting>
</settings>
<environments>
    <environment name="My distributed environment">
        <fs>
            <path>\\path\to\fileshare</path>
            <user>Domain\ServiceAccount</user>
            <password source="pwd" id="ServiceAccount"/>
        </fs>
        <db>
            <url>jdbc:urlTo/dbInstance</url>
            <user>dbUser</user>
            <password source="pwd" id="dbUser"/>
        </db>
        <auth>
            <url>ldaps://url</url>
            <default.domain>MyDomain</default.domain>
            <group.prefix>GROUP_PREFIX_</group.prefix>
            <group.filter>OU=SomeUnit,DC=my,DC=company,DC=com</group.filter>
        </auth>
    </environment>
</environments>
</config>

Some points to note:

  • A general block named settings can be used to define global settings that are re-used over multiple environments. In this case, a 'pwd dir' has been defined, which contains encrypted passwords for service accounts (see below).
  • The fs and db tags have been expanded to also contain accounts with write-access to the file share and database instance respectively. This approach can be used to manage security on the application-level (or rather, protocol-level), instead of creating accounts for each user individually on the file share and database instance.
  • The auth tag defines the authentication method. This is described in detail in the next topic.

Authentication setup

Without any authentication method configured, the user will have full admin-like access to the environment. This is only recommended in single-user environments. In multi-user environments, an authentication configuration should be specified, using the approach outlined below.

Authentication

The LDAP URL (given by the url tag) points to an LDAP-compatible server (such as Active Directory), against which users will be authenticated using a bind-operation. LDAP over SSL is supported, but requires setting up a keystore containing the appropriate certificates.

Authorization

Phaedra uses the concepts of Teams and Roles to manage access to protocols.

  • A protocol specifies the team that 'owns' the protocol, and thus has access to it.
  • A user may have one or more roles within that team, determining the type of access he has to the protocol(s).

Phaedra defines 4 roles:

  • READONLY: A team member with this role can only see data in a protocol, he cannot modify it.
  • USER: A team member with this role can see, import, modify and delete data in a protocol, but he cannot approve/disapprove plates.
  • MANAGER: A team member with this role can do the same as a USER, and in addition he can approve/disapprove plates.
  • ADMIN: A team member with this role can do anything in the protocol.

The tags group.prefix and group.filter allow Phaedra to build a list of security groups. Each LDAP group that is located in the filter and matches the prefix, will be added as a Phaedra security group. The group name should follow this pattern:

<PREFIX><TEAMNAME>_<ROLE>

For example, if the prefix is 'PHAEDRA-GROUP-', then valid group names would be:

PHAEDRA-GROUP-TEAM1_USER
PHAEDRA-GROUP-TEAM1_MANAGER
PHAEDRA-GROUP-TEAM2_USER
PHAEDRA-GROUP-TEAM2_MANAGER

Database setup

Note: this only applies to multi-user setups. In a single-user embedded environment, the database will be set up automatically on the first launch.

Installation

Installing the database is not in scope of this setup guide, however an example for installing a PostgreSQL database in Ubuntu is given below.

Open a shell and install the database software:

sudo apt-get install postgresql postgresql-contrib
sudo apt-get install pgadmin3

Run the psql prompt to define a password for the 'postgres' user:

sudo -u postgres psql postgres

In the psql prompt, enter:

\password postgres

Exit the psql prompt by entering Ctrl+D, and proceed with the configuration:

Note: your installation location may differ from the one given below.

sudo gedit /etc/postgresql/9.5/main/postgresql.conf

Add this line to listen on all network interfaces, instead of just localhost:

listen_addresses = '*'

Save and return to the command line:

sudo gedit /etc/postgresql/9.5/main/pg_hba.conf

Add the following lines to grant the phaedra accounts connection privileges:

host    all     phaedra             all     md5
host    all     phaedra_readonly    all     md5
host    all     phaedra_usr     all     md5

Note: for more information on these settings, see the PostgreSQL docs.

Finally, restart the service to apply the changes:

sudo service postgresql restart

Schema setup

Oracle

  1. Download or clone the Oracle setup scripts.
  2. Review setup1.sql and change the passwords, tablespace names and quota as needed.
  3. Execute setup1.sql as SYSTEM (or have a DBA execute the script).
  4. Log in to the phaedra database using the phaedra account (see setup1.sql).
  5. Execute setup2.sql
  6. Execute setup3.sql as SYSTEM (or have a DBA execute the script).
  7. Insert the JDBC URL into your config.xml file:

    jdbc:oracle:thin:@hostname:1521:dbName

Postgres

  1. Download or clone the Postgres setup scripts.
  2. Review setup1.sql and change the passwords and tablespace locations as needed.
  3. Make sure the tablespace folder exists and the postgres user has write permissions.
  4. Execute setup1.sql as the postgres user.
  5. Execute setup2.sql as the phaedra user.
  6. Insert the JDBC URL into your config.xml file:

    jdbc:postgresql://hostname:5432/dbName

File server setup

Note: this only applies to multi-user setups. In a single-user embedded environment, the file server will be set up automatically on the first launch.

Setting up the file server involves the following steps:

  1. Create one or more SMB shares on a Windows or Linux host (or more specialized hardware, such as a NetApp filer).
  2. Create a service account with write access on the shares.
  3. Copy the initial folder structure onto the shares.
  4. Obtain the path of the shares (e.g. an "smb://hostname/sharename" path or a "\hostname\sharename" UNC path) and insert them into your config.xml file.

SMB shares with Samba

In the examples below, we will create 2 separate shares:

  • phaedra_public, a share that can be viewed by anyone, containing connection parameters for the Phaedra client.
  • phaedra, the protected share containing all data stored for the Phaedra environment.

Start by defining an account and folders for the shares:

sudo useradd phaedra_smb_user
sudo passwd phaedra_smb_user
sudo smbpasswd -a phaedra_smb_user
sudo mkdir /mnt/phaedra_public
sudo chown phaedra_smb_user:phaedra_smb_user /mnt/phaedra_public
sudo mkdir /mnt/phaedra
sudo chown phaedra_smb_user:phaedra_smb_user /mnt/phaedra

Next, configure Samba to share the folders with appropriate security.
An example Samba configuration is given below:

[global]
workgroup = WORKGROUP
server string = %h server (Samba, Ubuntu)
dns proxy = no
log file = /var/log/samba/log.%m
max log size = 1000
syslog = 0
panic action = /usr/share/samba/panic-action %d
server role = standalone server
passdb backend = tdbsam
obey pam restrictions = yes
unix password sync = no
passwd program = /usr/bin/passwd %u
passwd chat = *Enter\snew\s*\spassword:* %n\n *Retype\snew\s*\spassword:* %n\n *password\supdated\ssuccessfully* .
pam password change = yes
map to guest = bad user

[phaedra]
path = /mnt/phaedra
writable = yes
valid users = phaedra_smb_user

[phaedra_public]
path= /mnt/phaedra_public
browsable = yes
read only = yes
guest ok = yes

Note that the phaedra_public share can be viewed by anyone, but is read-only. The phaedra share can be read and written only by the phaedra_smb_user account.

Populating the file shares

The public share should contain at least these two items:

  • A file config.xml, containing connection parameters for the Phaedra clients.
  • A folder pwd, containing encrypted password referenced in the config.xml file.

Phaedra client installations can refer to the config.xml file via their phaedra.ini file. See the topic Environment configuration above for details. For more information about the PWD folder and storing encrypted passwords in it, see the topic Using a PWD directory below.

The protected share should contain the initial folder structure that can be found here:

File server file list

Download or clone these files and copy them onto the protected share.

Update the config.xml file

Below is an example configuration for a setup with two Samba shares:

<config>
    <settings>
        <setting name="pwd.path">smb://samba-host/phaedra_public/pwd</setting>
    </settings>

    <environments>
        <environment name="Example Environment">
            <fs>
                <path>smb://samba-host/phaedra</path>
                <user>phaedra_smb_user</user>
                <password source="pwd" id="phaedra_smb_user" />
            </fs>
            ...
        </environment>
    </environments>
</config>

Using a PWD directory

Note: this only applies to multi-user setups. In a single-user embedded environment, no passwords are used.

Since the contents of the config.xml file are accessible to all Phaedra users, and possibly even the whole network, it should not contain plain-text passwords. Instead, you can use a PWD directory to store passwords in an encrypted format, and refer to the PWD directory from the config file. To enable the PWD directory, you must specify a setting named 'pwd.path' in the configuration's global settings section:

<config>
    <settings>
        <setting name="pwd.path">\\path\to\pwddir</setting>
    </settings>
    ...
</config>

An example of how to refer to a PWD-stored password is:

<password source="pwd" id="MyServiceAccount"/>

The attribute source="pwd" means that the value of the password will be retrieved from the PWD directory. The id attribute refers to the filename. For the example above, the PWD directory is expected to contain a file named MyServiceAccount.aes.

To add new passwords to the PWD directory, follow these steps:

  1. Open a command prompt
  2. Navigate to the folder where a Phaedra client is located
  3. Execute the following command:

    ./phaedra -application eu.openanalytics.phaedra.base.environment.passwordutil

You will be prompted to enter a name and password. After the command completes, a new file will be created in the directory, with the extension .aes. Copy this file to the PWD directory so it can be used by Phaedra clients to resolve the account password.