Getting Started with ThingWorx > Installing and Upgrading ThingWorx > RHEL Installation > PostgreSQL > Install and Configure PostgreSQL (RHEL)
  
Install and Configure PostgreSQL (RHEL)
The instructions provided below are intended for the PostgreSQL administrator (not the DB host servers).
* 
If you are including the HA layer to your implementation, refer to the ThingWorx High Availability Administrator’s Guide.
Install PostgreSQL and Create a New User Role
* 
These steps assume a version of RHEL with a GUI (X11) and an active account with access to the RHEL software repositories. If you are working without a GUI, skip installing PgAdmin III and refer to this support article for alternate instructions. If you do not have access to the official RHEL software sources, you can set up a free open source repository from the EPEL team. (this site is not provided or controlled by PTC).
1. Add the PostgreSQL repository to Yum and install.
2. Install PgAdmin III, the PostgreSQL admin tool:
$ sudo yum install pgadmin3
* 
To install PgAdmin III via the command line, reference https://wiki.postgresql.org/wiki/Manual_Setup_at_the_Command_Line.
3. Initialize and launch the database:
$ sudo /usr/pgsql-9.x/bin/postgresql9.x-setup initdb
Set the PostgreSQL service to start on boot:
$ sudo chkconfig postgresql-9.x on
$ sudo service postgresql-9.x start
4. Set up the password for the PostgreSQL user:
$ sudo passwd postgres
5. Enter the password for the PostgreSQL user. You will use this password in later steps.
* 
The password, which should not be easily guessed or a known, common password, should be at least 14 characters in length and include a mix of uppercase and lowercase letters, numbers, and special characters.
6. Set up the PostgreSQL user in psql:
* 
If the PostgreSQL database is not located on the same server as ThingWorx, then refer to the section Configure PostgreSQL Database Located on a Separate Server than ThingWorx and skip the next two steps. While it is optional to have the PostgreSQL database on the same server as ThingWorx in a development environment, it should be separate in all production environments.
$ sudo -u postgres psql -c "ALTER ROLE postgres WITH password '<unique PostgreSQL password>'"
* 
The <unique PostgreSQL password> value is what you entered above.
7. If using the command line, open the following files and edit as noted. Skip this step if using pgAdmin III.
/var/lib/pgsql/9.x/data/postgresql.conf/postgresql.conf: Uncomment listen addresses and port. The default settings of localhost and 5432 are usually sufficient.
/var/lib/pgsql/9.x/data/pg_hba.conf: Set Method to md5
8. Configure pgAdmin III. Skip this step if you are not using pgAdmin III.
$ sudo pgadmin3
In the pgAdmin III GUI, click on file->Open postgresql.conf
Open /var/lib/pgsql/9.x/data/postgresql.conf
Put a check next to listen addresses and port. The default settings of localhost and 5432 are usually sufficient.
Save and close.
Click on file->Open pg_hba.conf
Open /var/lib/pgsql/9.x/data/pg_hba.conf
Double-click on the database ‘all’ line with address 127.0.0.1/32
Set Method to md5
Click OK
Save and exit
Close pgAdmin III
9. Restart the PostgreSQL service:
$ sudo service postgresql-9.x restart
10. Set up PgAdmin III to connect to the database:
$ sudo pgadmin3
11. Click the plug icon to add a connection to a server in the top left corner and fill out the following:
Name: PostgreSQL 9.x
Host: localhost
Port: 5432
Service: <blank>
Maintenance DB: postgres
Username: postgres
Password: <unique PostgreSQL password as set previously >
Store password: Checked
Group: Servers
12. Click OK.
13. Create a new user role:
* 
The following command can be used if you are not using pgadmin:
sudo -u postgres psql -c "CREATE USER twadmin WITH PASSWORD '<unique postgres password>';"
b. Right click PostgreSQL9.x(localhost:5432).
c. Select NewObject>NewLogin Role. On the Properties tab, enter a name in the Role name field.
d. On the Definition tab, in the Password field, enter a unique password (you will be prompted to enter it twice).
* 
The password, which should not be easily guessed or a known, common password, should be at least 14 characters in length and include a mix of uppercase and lowercase letters, numbers, and special characters. You will need to re-enter this password in later steps.
e. Click OK.
Configure PostgreSQL Database Located on a Separate Server than ThingWorx
* 
This section is optional for development environments, but should be implemented in all production environments.
By default, the PostgreSQL server is installed in a locked-down state. The server will only listen for connections from the local machine In order to get ThingWorx to communicate to the PostgreSQL server, some configuration changes need to be made so that PostgreSQL knows to listen for connections from other users (thingworx user, default is twadmin) and/or other machines (ThingWorx installed on a separate server).
You will need to know where your PostgreSQL data directory resides for these steps. On Linux, the location of the data folder, or even the configuration files can change based on distribution and installation method (download or package manager install). This location will be referred to as <PGDATA> in these instructions.
Modify the pg_hba.conf file and add the following lines based on your desired configuration:
If you want to allow all IPv4 addresses to connect:
host all all 0.0.0.0/0 md5
If you want to allow only a specific IPv4 address to connect (Replace <ipAddress> with the IP address of the machine making the connection):
host all all <ipAddress>/32 md5
If you want to allow all IPv6 addresses to connect:
host all all ::0/0 md5
If you want to allow only a specific IPv6 address to connect (Replace <ipv6Address> with the appropriate address):
host all all <ipv6Address>/128 md5
Any other combination is possible by using additional allowance lines (individual IPs or ranges) or subnet masks appropriate to the machines that require access to the PostgreSQL database.
Any change to this file requires a restart of the database service.
* 
For additional information about configuring the pg_hba.conf file, see the official PostgreSQL documentation (9.4).
Enabling PostgreSQL to listen for all Connections
On Linux installations of PostgreSQL, there is an additional configuration step required to configure the PostgreSQL server to listen for connections.
1. In the postgresql.conf file, uncomment and update the listen_addresses line:
Uncomment the listen_addresses line and change localhost to '*'
# Listen on all addresses. Requires restart.
listen_addresses = '*'
2. Restart the PostgreSQL server.
Configure and Execute the PostgreSQL Database Script
To set up the PostgreSQL database and tablespace, the thingworxPostgresDBSetup script must be configured and executed.
1. Create a folder named ThingworxPostgresqlStorage on the drive that the ThingworxStorage folder is located (in the root directory by default).
* 
If you create the folder using the -d<databasename> command, you do not have to use the PostgreSQL user.
* 
You must specify the -l option to a path that exists. For example, -l D:\ThingworxPostgresqlStorage. The script does not create the folder for you.
* 
The folder must have appropriate ownership and access rights. It should be owned by the same user who runs the PostgreSQL service, and have Full Control assigned to that user - this user is generally NETWORK_SERVICE, but may differ in your environment.

$ sudo mkdir /ThingworxPostgresqlStorage
$ sudo chown postgres:postgres /ThingworxPostgresqlStorage
$ sudo chmod 755 /ThingworxPostgresqlStorage
2. Obtain the thingworxPostgresDBSetup script from the ThingWorx software download package. The script is located in the install folder. ThingWorx downloads are available in  PTC Software Downloads.
3. If necessary, configure the script. Reference the options in the table below.
* 
This example uses the 8.3.x download from the PTC site. If necessary, change the file name to the version you are using.

$ sudo unzip MED-61111-CD-083_ThingWorx-Platform-Postgres-8-3-x.zip
$ cd install
4. To set up the database and tablespace with a default PostgreSQL installation that has a PostgreSQL database and a PostgreSQL user name, enter:
$ sudo sh thingworxPostgresDBSetup.sh -a postgres -u <user role name> -l /ThingworxPostgresqlStorage
5. Execute the script.
thingworxPostgresDBSetup Script Options
Option
Parameter
Default
Description
Example
t or -T
tablespace
thingworx
Tablespace name
-t thingworx
-p or -P
port
5432
Port number of PostgreSQL
-p 5432
-d or -D
database
thingworx
PostgreSQL Database name to create
-d thingworx
-h or -H
host
localhost
Name of the host
-h localhost
-l or -L
tablespace_location
/ThingworxPostgresqlStorage
Required. Location in the file system where the files representing database objects are stored.
-l or -L
-a or -A
adminusername
postgres
Administrator Name
-a postgres
-u or -U
thingworxusername
twadmin
User name that has permissions to write to the database.
-u twadmin
Configure and Execute the Model/Data Provider Schema Script
To set up the PostgreSQL model/data provider schema, the thingworxPostgresSchemaSetup script must be configured and executed. This will set up the public schema under your database on the PostgreSQL instance installed on the localhost.
1. Obtain and open the thingworxPostgresSchemaSetup.bat from the ThingWorx software download package. The script is located in the install folder.
2. If necessary, configure the script. Reference the options in the table below.
* 
The script can be run with the default parameters as:
$ sudo sh thingworxPostgresSchemaSetup.sh
3. Execute the script.
* 
The username should match the PostgreSQL username that was previously created.
thingworxPostgresSchemaSetup Script Options
Option
Parameter
Default
Description
Example
-h or -H
host
localhost
IP or host name of the database.
-h localhost
-p or -P
port
5432
Port number of PostgreSQL.
-p 5432
-d or -D
database
thingworx
Database name to use.
-d thingworx
-s or -S
schema
public
Schema name to use.
-s mySchema
-u or -U
username
twadmin
Username to update the database schema
-u twadmin
-o or -O
option
all
There are three options:
all: Sets up the model and data provider schemas into the specified database.
model: Sets up the model provider schema into the specified database.
data: Sets up the data provider schema into the specified database.
-o data
Configure platform-settings.json
1. Create a folder named ThingworxPlatform at the root of the drive where Tomcat was installed or as a system variable.
* 
To specify the location where ThingWorx stores its settings, you can set the THINGWORX_PLATFORM_SETTINGS environment variable to the desired location. Ensure that the folder referenced by THINGWORX_PLATFORM_SETTINGS exists and is writable by the Tomcat user. This environment variable should be configured as part of the system environment variables.
* 
The ThingWorx server will fail to start if it does not have read and write access to this folder.
2. Place the platform-settings.json file into the ThingworxPlatform folder. This file is available in the software download.

$ sudo cp platform-settings.json /ThingworxPlatform/
3. Open platform-settings.json and configure as necessary. Refer to the configuration options in platform-settings.json Configuration Details.
* 
If your PostgreSQL server is not the same as your ThingWorx server, and you are having issues with your ThingWorx installation, review your Tomcat logs and platform-settings.json file. The default installation assumes both servers are on the same machine.
Encrypt the PostgreSQL Password
Encrypt the password by following the steps in Encrypting Passwords
Installing the PostgreSQL Client Package and PostgreSQL User (optional)
In order to issue PostgreSQL commands from the client machine to the PostgreSQL server, do so from a PostgreSQL user. The postgresql-client-9.x package can be installed on the client machine, refer to your distributions documentation on how to install it. This package provides some administration tools such as psql.
Install ThingWorx
Go to Install ThingWorx.