Installing the Database

 

Before you begin, please be aware that it is not necessary to install the xTuple database locally. You can download the xTuple Desktop Client Installer and apply for a Free Trial account, in which case xTuple will create a database for you on the xTuple Cloud. If you prefer to have the database on a local computer, however, please follow the instructions below.

If the command line is your preference, we have command line examples for you to follow. There are also simple GUI approaches, as described in the pgAdmin section.

For additional information, you might also read Perry Clark's blog post "Installing PostBooks... the long way."

Quick Overview

This quick overview assumes you are not using the Free Trial.

  1. Download and extract the xTuple ERP client application to a local directory
  2. Download and install PostgreSQL
  3. Initialize PostgreSQL for xTuple (This simply means adding the super user 'admin' and the group 'xtrole'.)
  4. Create a database using UTF-8 encoding
  5. Download and restore an xTuple database on your new database

PostgreSQL Considerations

Before you can start using xTuple ERP, make sure to check the Compatibility Matrix page for the latest details on which PostgreSQL version will work best with your xTuple ERP version.

For information related to easy database administration using the open source tool pgAdmin, please see the pgAdmin section below. And for additional information related to installing PostgreSQL, please visit www.postgresql.org where you will find in-depth documentation and other resources related to PostgreSQL.

xTuple ERP uses encryption for credit card processing--and because of this, the PostgreSQL "pgcrypto" module is required to support encryption in xTuple ERP. You should be sure to include the pgcrypto module when installing PostgreSQL. If you do not, you will encounter errors.

Detailed Instructions

The following paragraphs detail the steps (long version) required to both initialize your PostgreSQL instance to support the xTuple Database and load the database schema. To skip these details, see the (short version) Command Line Examples section below. Or skip to the pgAdmin section below to learn about initializing and loading your database using pgAdmin, a free GUI database administration tool.

Once you have the PostgreSQL server running, the next step is to establish the user 'admin' and the group 'xtrole' on your PostgreSQL instance. This is done by executing the 'init.sql' script, which is available in the downloads area.

The complete text of the 'init.sql' file is as follows:

-- ** PLEASE NOTE, THE GROUP ROLE IS NOW 'xtrole', not 'openmfg'
-- This script creates the group xtrole and the user admin --
--
-- Create the xtrole group

CREATE GROUP xtrole;
--
-- Create the admin user with createdb and createuser
-- permissions. Place the user in the xtrole group and
-- set the password to the default of admin.
--
CREATE USER admin WITH PASSWORD 'admin'
CREATEDB CREATEUSER IN GROUP xtrole;
-- End of init.sql

If you are initializing the database server instance from the command line, the 'init.sql' script must be loaded by the 'postgres' superuser. This is not required if you are using pgAdmin to initialize the database server.

Please also note that since the default password the admin user is "admin," you'll want to change it immediately. You may create a different admin user with a different name if you choose to. However, do this with caution as all documentation examples refer to the default admin user.

When you have finished executing the init.sql script, you should next create a new PostgreSQL database to contain the xTuple Database schema. Use UTF-8 encoding when creating the database. You can name the database anything you want. Shorter names that are easy to remember are preferred.

Once the database has been created, you are ready to load the xTuple schema into it. There are several starter schema to choose from, including the following:

  • empty.backup - This is an empty database with no data, but all the tables and structures created.

  • quickstart.backup - This database contains a basic Chart of Accounts and also the Account Assignments required to run the full range of transactions.

  • demo.backup - This database (if available) contains a suite of sample data built on top of the 'quickstart' database

Like the init.sql script, the database schema can be loaded on the command line. Alternately, you may use GUI tools like pgAdmin III to execute the script and load the schema. For information on loading the databases using pgAdmin, please see the pgAdmin section below.

The '.backup' format of the xTuple Database schemas is a compressed format used by the pg_restore binary. This format may be loaded seamlessly using pgAdmin. To load a .backup file using pgAdmin, connect to the database you created. Right-click on the database object and select the option 'Restore'. On the resulting screen, use the ellipses to navigate to the location of the .backup file on your local machine. With the .backup file selected, simply click OK.

To learn more about the psql utility or the pgAdmin application, please consult the PostgreSQL documentation.

Command Line Examples

The following examples demonstrate the steps needed to initialize, create, and load an xTuple Database. You may give the database you create any name which does not conflict with the rules for naming PostgreSQL databases. However, we recommend that you choose a simple name with all lowercase characters. For example, we have used a database named 'production' in the following example.

With a clean PostgreSQL instance installed, you can use the following commands to get started:

psql -U postgres -f init.sql template1
createdb -U admin production
pg_restore -U admin -d production quickstart.backup -v

The first command line example uses the 'psql' utility to load the 'init.sql' script. This script creates the user 'admin' and the group 'xtrole'. The first option ('-U postgres') tells the system to connect as the postgres user. This user is typically the default PostgreSQL superuser. The next option ('-f init.sql') tells psql to read the init.sql script and execute the commands. The last option ('template1') tells psql which database to connect to.

You are not required to run the init.sql script against the 'template1' database. You may also run it against another database you create. Also: In newer versions of PostgreSQL, the 'postgres' database is the new default template.

By default, the init.sql script will create the 'admin' user with the password of "admin". You should be sure to change the password once you have your xTuple system installed and running.

The second command line example uses 'createdb' to create a new database. Notice that this command uses the same first two options as used in the psql command to specify the user to connect as. Note that now we are using the option '-U admin' to indicate we want to connect as the admin user created previously. The last option is the name of the new database we want to create (e.g., 'production').

The third command line example loads the schema for the xTuple 'quickstart' Database. The .backup file format is a compressed format and is used by the pg_restore binary. The -d switch enables you to specify the database into which the restore will be performed (i.e., the 'production' database in this example.) Next, we specify the name of the .backup file with the path to its location if necessary. Finally, we specify -v for verbose output.

It is important to keep in mind that if you configured PostgreSQL to listen on a port other than the default port of 5432, you will need to specify this with '-p XXXX' where XXXX is the port number.

If you want a .sql file instead of a .backup, you can easily do this using pg_restore, as follows:

pg_restore -f quickstart.sql quickstart.backup

This example says use pg_restore to create a file called 'quickstart.sql' from the file called 'quickstart.backup'.

This completes the command line examples section.

Using pgAdmin To Get Started

pgAdmin is a free, cross-platform GUI tool for administering PostgreSQL databases. In this section we assume you have PostgreSQL already installed on your system. The following screenshots and narrative describe how to get xTuple ERP running on your PostgreSQL server.

We will describe how to accomplish two main objectives:

  1. Configuring PostgreSQL for xTuple
  2. Loading the xTuple database(s)

Configuring for xTuple

Since you already have PostgreSQL installed, the first thing to do is initialize the server so xTuple databases will run successfully on it. While that last sentence may sound complicated, the reality is you only have to do the following things:

  1. Link pgAdmin to your PostgreSQL server
  2. Create a group called "xtrole"
  3. Create a user "admin"
  4. Put the user "admin" in the group "xtrole"

This section assumes you installed PostgreSQL on your local drive (a.k.a. "localhost" or "127.0.0.1").

Okay, so the first thing to do is to create a link between your pgAdmin application and your PostgreSQL database. If that link already exists, then you can skip this step. But if not, simply select the "File" menu option and then select the "Add Server" option.

Add New Server

AddServer.png

When you are presented with the new server screen, enter the information as it's shown in the next screenshot. You have flexibility in some of the options you choose. However, the following must be used:

  • Host = localhost or 127.0.0.1
  • Port = 5432
  • Username = postgres
  • Password = Password used for postgres user when you installed PostgreSQL

Server Definition

ServerDefinition.png

Once you have the connection between pgAdmin and PostgreSQL completed, the next step is to configure PostgreSQL so xTuple databases will run successfully on it. The first thing to do then is to create the "xtrole" group. By right-clicking on the Group Roles section, you can select the "New Group Role" option.

Group Roles

When creating the new group role for "xtrole", you only need to enter a minimal amount of information. Enter the same information as it's shown in the next screenshot. The Role name should be lower case. And the only Role Privilege you need is "Inherits rights from parent roles". That's it. No password required. And you don't have to add any information under the other tabs that are shown.

Group Role for xtrole

Now that you have the "xtrole" group role define, the next step is to create the "admin" user and place the user in the group "xtrole". The next screenshot shows how you can access the screen for creating a new login role.

Login Roles

LoginRoles.png

The screen for creating a login role for "admin" looks similar to the screen we saw before for creating the "xtrole" group. However, this time we will need to add more information--and select more options. You have some flexibility over some of the options you choose, but the following should be the same as shown in the screenshot:

  • Role name = admin
  • Role Privileges = Select all

If you don't need the account to expire at a certain point, then just leave the expiration date blank. That will keep the account open indefinitely.

Login Role for admin User

AdminRole.png

Once the "admin" user's properties have been defined, select the Role membership tab. It's on this screen you make the user "admin" a member of the group "xtrole". The following screenshot shows the end result of this action. By using the double arrows ">>" you can move "admin" from not being a member in "openmfg" to being a member in "openmfg".

Admin in Group xtrole

And that's all you need to initialize PostgreSQL for xTuple. You can now load xTuple ERP databases onto the server and connect to them using your xTuple ERP client application.

Creating New Database

The last getting started step is to create a database and load (i.e., restore) an xTuple ERP backup file into it. The next screenshot shows how right-clicking on the "Databases" element enables you to access the "New Database" option.

List of Databases

DatabaseList.png

You can name your database anything you want to. In our example we will be calling our new database "dbTest". When you are creating a new database with pgAdmin, be sure to use the following values, as shown in the screenshot:

  • Owner = admin
  • Encoding = UTF8
  • Template = template1

You can leave everything else with the default values pgAdmin gives you. And there's no need to enter additional information under any of the other tabs.

Create New Database

NewDatabase.png

The database we just created now appears in the list of databases, as you can see in the next screenshot. Our final step is now to load an xTuple database backup file into the database we created. For the purposes of this example, we will assume you have already downloaded the database backup file from either the PostBooks site on SourceForge--or from the xTuple website (Standard and Manufacturing Editions only).

Restoring from Backup File

As the next screenshot shows, we can reach the "Restore" option by right-clicking on the new database we just created. The "Restore" option is the one we need to load the xTuple .backup file.

Restore Backup File

RestoreBackup.png

The Restore screen looks just like the next screenshot. All you have to do here is

  1. Browse your computer for the xTuple .backup file you downloaded
  2. Select it the .backup file so the path to it appears in the "Filename" field

You should leave the other options not-selected--except for the last one, which will give you more verbose messaging during the load process (this can be helpful). And then simply select the OK button to begin the restore process.

Begin Restore

BeginRestore.png

Don't worry if the restore takes several minutes to complete. This is normal. At the end of the process you will see log messages which look like those shown in the following screenshot. Depending on the circumstances of your PostgreSQL installation (e.g., whether previous databases have been installed there, etc.), the messages pgAdmin reports may vary. The ideal scenario on a fresh PostgreSQL install is for 0 errors to be reported and an exit code = 0. However, as the next screenshot shows, pgAdmin may report a number of errors and a non-zero exit code. If this is the result you get, don't be alarmed. Simply review the list of errors by using the scroll bar in the "Restore Database" screen. Scroll to the top and review the list of errors which were reported. Most if not all of the errors you get can safely be ignored.

Here are some examples of error messages which can safely be ignored. The first error reports that the PostgreSQL procedural language plpgsql is already installed--and so it does not need to be restored:

pg_restore: creating PROCEDURAL LANGUAGE plpgsql
pg_restore: [archiver (db)] Error while PROCESSING TOC:
pg_restore: [archiver (db)] Error from TOC entry 2121; 2612 48797691 PROCEDURAL LANGUAGE plpgsql
pg_restore: [archiver (db)] could not execute query: ERROR:  language "plpgsql" already exists
    Command was: CREATE PROCEDURAL LANGUAGE plpgsql;

Likewise, you may see other messages such as the following two, which both indicate functionality already exists and does not need to be restored from the .backup file:

Example 1:

pg_restore: [archiver (db)] Error from TOC entry 18; 1255 7469922 FUNCTION armor(bytea) admin
pg_restore: [archiver (db)] could not execute query: ERROR:  function "armor" already exists with same argument types
    Command was: CREATE FUNCTION armor(bytea) RETURNS text
    AS '$libdir/pgcrypto', 'pg_armor'
    LANGUAGE c IMMUTABLE STRICT;

Example 2:

pg_restore: [archiver (db)] Error from TOC entry 20; 1255 7470043 FUNCTION crypt(text, text) admin
pg_restore: [archiver (db)] could not execute query: ERROR:  function "crypt" already exists with same argument types
    Command was: CREATE FUNCTION crypt(text, text) RETURNS text
    AS '$libdir/pgcrypto', 'pg_crypt'
    LANGUAGE c IMMUTABLE STRICT;

In short, you should review any error messages you get when restoring an xTuple database backup file. However, in many cases the errors that are being reported can safely be ignored. Use your common sense when reviewing error messages. If you come across an error message which concerns you, search the xTuple forums to see if others have been concerned about the same thing. Quite often others in the community will have seen the same errors you are concerned about.

Once the restore is completed, select the OK button.

Restore Complete

RestoreComplete.png

To see that the restore operation loaded the xTuple database successfully, simply refresh your pgAdmin view. Then expand the new database element to see the xTuple schema (i.e., tables, functions, etc.) listed under the Schema element. The following screenshot shows the "api" and "public" schema found in every xTuple database.

Database Schema Loaded Successfully

DbSchema.png

So that's all you have to do. Now simply locate your xTuple client application and open it up. Then use the following login options:

  • Server = localhost or 127.0.0.1
  • Database = dbTest (or whatever you named yours)
  • Port = 5432
  • Username = admin
  • Password = admin

You can use the same steps described above to add more databases to your PostgreSQL server. However, if you are running a production database, we recommend that you run only the production database on the server--and don't load other databases onto the same PostgreSQL instance.