# 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 administration 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>
</fs>
<db>
<url>jdbc:urlTo/dbInstance</url>
<user>dbUser</user>
</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


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 = '*'


	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_usr		all		md5


Finally, restart the service to apply the changes:

	sudo service postgresql restart


### Schema setup

#### Oracle

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

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
passwd program = /usr/bin/passwd %u
map to guest = bad user

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

[phaedra_public]
path= /mnt/phaedra_public
browsable = 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>
</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.

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