Difference between revisions of "Adempiere Install for Windows & PostgreSQL"

Revision as of 18:01, 18 July 2010

This install process applies to Windows XP and Vista operating systems and the PostgreSQL database.

Introduction

This installation instruction is intended for initial installations where the database, application server and client all run on the same machine. For more complex installations, see InstallServer.

An installation can take as little as 15 or 20 minutes if you start with the required downloads and do everything correctly.

Other alternatives you might want to investigate are the Windows Installer or VMWare/VirtualBox AVA packages. However, the following method will give you much more control over the installation including upgrades with the latest patches and scripts.

Note: If you are using Windows VISTA, make sure that User Account Control (UAC) is turned off through user accounts or be sure to run the processes with administrative privileges. To start a DOS shell with Admin rights, go to the start menu (Start{{#if: All Programs | →All Programs }}{{#if: Accessories | →Accessories }}{{#if: | → }}), right-click on the "Command Prompt" icon and select "Run as Administrator".

Downloads

Before you begin, download each of the following packages:

• Java SE Development Kit - Get the latest from http://java.sun.com/javase/downloads/index.jsp. You only need the JDK without JavaFX, EE or NetBeans bundles.
• Postgre SQL - Get the latest Windows install from http://www.postgresql.org/download/windows.
• ADempiere Latest Release - Download the latest Adempiere from http://sourceforge.net/projects/adempiere/files/ADempiere Official Release.
• ADempiere Patches - From http://sourceforge.net/projects/adempiere/files/ADempiere Patches/ download the patches for the version of ADempiere downloaded above. The patches come in two files, a *_patches_*.jar and a *_migra_*.zip. You will need both.

Install the Pre-Requisites

JAVA

Install the JAVA JDK with the default installation settings. Say OK to install the follow-on JRE as well.

Open Windows Explorer and navigate to the C:\Program Files\Java directory (or where-ever your Java is installed) and carefully note the full path for the JDK directory (e.g: C:\Program Files\java\jdk1.5.0_19) and the JRE directory that you have just installed.

Note: There may well be a number of JDK and JRE directories, so choose the right ones! The JDK should include the JRE.

Set the JAVA Environment Variables

Caution! You need to get the paths below absolutely right or nothing else will work! No pressure.

On your Desktop (or using Start button / My Computer) right click My Computer and select System Properties / Advanced / Environmental Variables (Alternatively: Start{{#if: Control Panel | →Control Panel }}{{#if: System | →System }}{{#if: Advanced tab | →Advanced tab }}) Add a new System Variable JAVA_HOME for your new JDK directory:

JAVA_HOME use C:\Program Files\Java\jdk1.5.0_19 (or whatever your JDK directory is called)

Back in My Computer / System Properties / Advanced / Environmental Variables, find the Path variable and click Edit. Append the following JRE and PostgreSQL paths to the end of Path variable after putting in a connector semi-colon ";"

%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;%JAVA_HOME%\jre\bin\client

Caution! Do not delete or overwrite the paths that are already in the Path variable! Also, make sure you don't have an extra "\" at the end of path.

IN a DOS shell, type PATH and Carefully check the result to ensure the two paths are correctly added to the PATH.

PostgreSQL

Note: You can use an existing installation of PostgreSQL if you already have one. If so, gather the passwords for the postgres user, check the environment variable and path, verify that the service is running and move on to the next step.

Install PostgreSQL by running the Windows executable installer downloaded above.

Installation options:

Account name: postgres

Password: postgres (or whatever you want - but write your password down! - let me repeat - !!write it down!!)

Port 5432 (the default port)

Note: If you receive an error message that the port is already in use, you probably have an old Postgres service running. Go to Control Panel/Administrative Tools/Services, find Postgres Database Server, Stop the service and set its startup to Manual. Try again.

Select your Locale and make sure the "pl/pgsql" box is ticked (which is the default)

Uncheck the box "Launch Stack Builder at exit" and Finish. Cancel out of Stack Builder if it insists in launching

Create an environment variable POSTGRE_HOME set to the PostgreSQL install directory, for example "C:\Program Files\PostgreSQL\8.4"

Edit the PATH variable again and add %POSTGRE_HOME%\bin to the end of the path. This will make it easy to run the psql command from any directory.

Start the PostgreSQL service. There will be a menu item in the PostgreSQL Start Menu to start the PostgreSQL service. It may already be running following the install. Check the running Services (Control Panel/Administrative Tools/Services). Congratulations, you now have Postgres database running

Install the ADempiere Software

There is no install script. Just extract the Adempiere zip file to <drive letter>:\ (e.g. c:\).

Note: You should end up with the files in a folder like C:\Adempiere. Do not extract to C:\Program Files\Adempiere. The batch scripts do not like the long file names with spaces. Also make sure you haven't created a chained directory like C:\Adempiere\Adempiere.

Apply the Patches

Patches are a combination of *.jar files, which replace *.jar files in the C:\ADempiere\lib directory, and migration scripts which update the database. In the Patches directory on Source Forge, there may be more than one type of *.jar that needs patching. If you downloaded one or more patch files, replace the existing file with the downloaded one, changing its name to match. For example, copy the *_patches_*.jar file to C:\Adempiere\lib\patches.jar, overwriting the existing file. See the detailed instructions in Patches Installation.

Note: If you are updating a patch file, it is a good idea to rename the existing *.jar file to something like patches.jar.old.

Apply Customizations, Packages and other Files

If you have a customization.jar with customized code or a packages.jar file with supporting *.jar files, add them to the C:\Adempiere\lib directory, overwriting the existing files.

Also, if you have other customized files, such as *.bat files, a CustomReport.war file, etc..., don't forget to add them. If you don't know what this means, it doesn't apply to you. Yet. (It is useful to developers who want to add customized components to the install.)

Initial ADempiere Setup

A setup utility in ADempiere will prepare the software for use and create environment variables needed in the following steps.

Open a DOS shell with administrative privileges. Admin privileges are important here as the setup process will need to set environment variables.

Navigate to C:\adempiere and execute RUN_setup.bat. If this is the first time you are running this, a licence and security keys dialogs will appear. Accept the defaults.

The setup dialog will appear.

You will need to change:

• Database Server from <your-computer-name> to localhost
• Database Type from oracleXE to postgresql
• Database Name from xe to adempiere
• System Password to postgres (or whatever you entered above for the database administrator)
• Database Password to adempiere
• Don't change anything in the Mail Server settings unless you want to set-up Adempiere for production purposes

You may also need to change the following:

• Adempiere Home to C:\Adempiere (if somehow it has been set to the wrong location)
• Application Server Web Port to 8080 (if 80 is being used by something else) and SSL to 8443 (instead of 443)

Press the Test button

When the Test completes without errors and the Save button (bottom, right) is activated, click the Save button. Wait a few minutes until the Adempiere Server Setup screen disappears and the deployment is finished.

Note: The database does not have a user adempiere or a database adempiere at this point, so these tests will not be checked. The user and database will be created in the next step.

If you are having problems, see the detailed instructions on this dialog in the pages InstallServer and ServerSetupHelp

Import ADempiere Example Data

Caution! The following script will DROP any existing adempiere database. Do not run this command if you already have data loaded.

Open a DOS shell.

Navigate to C:\Adempiere\utils Type 'RUN_ImportAdempiere.bat'

See CreateDatabase for more information.

Apply Migration Scripts

If you are not installing patches, skip this step.

The database installed above will be at the state of the release version. If you are updating with patches, you will also need to apply migration scripts to modify the database to keep it in sync with the software. The migration scripts can be found in the *_migra_*.zip file downloaded above. Unzip the contents to a convenient directory.

Open a DOS shell and change to the directory where you saved these scripts. The script should all have a preface number. Starting at the lowest number and ascending, for each of the *.sql files, run:

psql -f <number>.sql adempiere adempiere

You will need to enter the password adempiere each time.

If there is a tediously large number of scripts, try the following:

1. Setup a '.pgpass' file according to the instructions for your version of PostgreSQL (for 8.4, see 30.14. The Password File). This will prevent the password entry each time you run the psql command.
2. From a DOS shell, navigate to the directory where the scripts are located and execute this command:

   FOR %N IN (*.sql) DO psql -f %N adempiere adempiere

Run Adempiere

Start the Application Server

Open a DOS shell Navigate to C:\Adempiere\utils Type 'RUN_Server2.bat' and wait for the server to fully start - it will end this phase with "INFO [Server] JBoss .... Started in xx:xx:xx ms", which will be around 2 to 3 minutes

Note: Leave this DOS shell running. Later, to shut down the Application Server, you can either RUN_Server2Stop in another DOS Shell or simply close the shell.

If you would like to run the server as a service, in a DOS shell, navigate to C:\Adempiere\utils\windows and run Adempiere_Service_Install.bat. You will need to open the Services Window (Control Panel{{#if: Administrative Tools | →Administrative Tools }}{{#if: Services | →Services }}{{#if: | → }}) to set the properties so the service starts automatically or manually.

Start the Adempiere Java Client

To start Adempiere, you can:

• just click the light blue Desktop icon Adempiere
• go to Webstart, which is the preferred method following supplementary patch upgrades that may alter the client!
  • using your browser http://<your computer name>/admin and click the blue button on the right hand side
  • Note that this admin screen will also have:
    • various HTML interfaces (see Using Adempiere's HTML Client below)
    • Point of Sale (POS) system
    • Webstore
• otherwise:
  • Open a DOS shell with Start Button / Run / Open: cmd
  • Navigate to C:\Adempiere\
  • Type RUN_Adempiere.bat

You will see either a login screen or a connection setting window:

• if you have a login screen labeled Connection, the Server will probably be a pink line. This normally means you need to fix some settings However, it may be pink simply because this is your first login. Try to click the green tick and proceed to login. If you can't do this then you will need to click the pink line so the Adempiere Connection window opens
• if you find yourself at the Adempiere Connection window, enter <your-computer-name> for the Application Host. Click Test Application Server and it should result in a green tick. In addition, it will probably sort out the Database parameters.
• click Test Database, which should also result in a green tick
  • Vista Users may need to sort out security - if when you Test Application Server you get a green tick but a red cross when you test the Test Database Server, you have a problem with PostgreSQL security on your computer. As a safety feature PostgreSQL will only let you access it if you are NOT an administrator, which helps to stop any hackers in the real world.
    • Solution for Vista users: Make a new user on your computer. Name it "postgres" and make sure its a standard user, NOT ADMIN. Now run the Setup.bat (same settings should still be there). Click save. Then run the RUN_Server2.bat and then RUN_Adempiere.bat. Do the test now and it should work. Also, make sure that your Application server has your computer name (ie Gregs_PC) and the Database server has localhost
• Select the green tick to close the Adempiere Connection window

Log in to check that everything is working

• Login to Adempiere as GardenAdmin with password GardenAdmin. As mentioned above, you should be able to simply click the green tick, which may take a few seconds to move on to the next screen. Accept the defaults (or perhaps change the printer) and click the second green tick. Hey presto - the Java Client will open!

Congratulations!!!

Using Adempiere's HTML Client

You can use a Web Browser instead of the Java Client by pointing your browser to: http://<your-computer-name>/admin and selecting the Adempiere ZK webUI option, which will open http://<your-computer-name>/webui

• On the first login screem enter the following parameters:
  • UserId: GardenAdmin
  • Password: GardenAdmin

• on second login screen enter:
  • Role: GardenWorld Admin
  • Client: GardenWorld
  • Organisation: HQ (you need to select this from the dropdown box)
  • Warehouse: HQ warehouse (will come up automatically)

Very Important - An ERP system is a journey and not a destination

If you want to keep your Adempiere installation up to date then you need to continue to Patch your Adempiere.

See Patches_Installation for a manual on how to install patches.

Uninstalling Postgres & Adempiere

Postgresql

• Start Button / All Programs / Postgresql 8.3 /Stop Service
• Start Button / Control Panel / Add or remove programs / Postgresql 8.3 remove
• Delete directory C:\Program Files\Postgresql
• Start Button / Run / cmd enter command net user postgres /delete
• Start Button / right click My Computer / Properties / Advanced / Environmental Variables / Edit Path to remove entry for postgresql

Adempiere

• Delete directory C:\Adempiere
• Delete file C:\Documents and Settings\<your user name>\Adempiere.properties
• Start Button / Control Panel / Add or remove programs / Adempiere anything remove

Java Development Kit and Runtime Environment

• Start Button / Control Panel / Add or remove programs /
  • J2SE Development Kit 5.0 Update xx remove
  • J2SE Runtime Environment 5.0 Update xx remove
• Start Button / right click My Computer / Properties / Advanced / Environmental Variables:
  • Remove the JAVA_HOME and JRE_HOME variables
  • Edit Path to remove entries for jre

old notes

However, you may need to do the following things first:

• • If you are re-installing a fresh version of Postgresql then remove various files and the postgres user - see Uninstalling Postgres & Adempiere below (however, do not remove the path reference in Environmental Variables).
  • If you are using Vista then you need to deactivate User Access Control from Control Panel and install PostgreSQL by right clicking and selecting Run AS Administrator. If you don't have "Run As Administrator" on the context menu, then install the following registry fix: http://www.symantec.com/connect/sites/default/files/MsiRunAsAdmin.zip

Step 5

Steps 5 & 6 are only for PostgreSQL 8.1 or earlier and where PL/Java has not already been installed.

Edit file C:\Programmi\PostgreSQL\8.2\data\postgresql.conf (C:\Program Files\PostgreSQL\8.2\data\postgresql.conf). Add the following lines:

International Version (POSTGRESQL 8.2 version adds the first 3 lines by default during Postgresql installation)

custom_variable_classes = 'pljava'
pljava.classpath = 'C:\\Program Files\\PostgreSQL\\8.2\\share\\pljava\\pljava.jar'  
pljava.release_lingering_savepoints = true
pljava.vmoptions = '-Xmx64M -Dbackchannel.port=48'
pljava.debug = false

Italian Version

custom_variable_classes = 'pljava'
pljava.classpath = 'C:\\Programmi\\PostgreSQL\\8.1\\share\\pljava\\pljava.jar' 
pljava.release_lingering_savepoints = true
pljava.vmoptions = '-Xmx64M -Dbackchannel.port=48'
pljava.debug = false

• Connection Settings (* indicates listen for connections on all hosts, remember to specify the host ip addresses in pg_hba.conf file, otherwise you will get database connection refused error while installing adempiere, this option is set by postgresql installation if it this option is selected in version 8.2 during the installation)

listen_addresses = '*'

pg_hba.conf

• TYPE DATABASE USER CIDR-ADDRESS METHOD

host all all 127.0.0.1/32 trust
host all all 192.168.1.1/24 trust

Step 6

Stop and restart PostgreSQL

Old notes - may not be relevant

• From http://www.adempiere.com/wiki/index.php/Release_342s go to the section Detected installation problem in postgresql 8.3.5 and download the necessary substitution files to your desktop (this is very important)
• Again from http://adempiere.com/wiki/index.php/Release_342s pick the link to Adempiere scripts and download the latest Adempiere scripts. NOTE: Be sure to get the scripts from the postgresql sub-directory rather than the directory you first see when you click the link! For the most recent version of each script, click download and save the resulting page to a new folder C:\adscripts. The browser's Save should automatically keep the right name for you. After downloading all the scripts, rename each of the files as just <number>.sql, for example 372.sql (Additional note for clarification: you do not need the migration script from 3.4.0 to 3.4.2 for a fresh installation.)

• Copy the substitution files that you downloaded above in respect to Detected installation problem in postgresql 8.3.5 from your desktop to C:\Adempiere\utils\postgresql where these new files will overwrite existing files

Establish the Initial Adempiere User & Database

Open pgAdmin III from Start Button / PostgreSQL / pgAdmin III

Right click on the Postgresql database server you want to use for ADempiere and select connect. Enter the password postgres (or whatever you used as the superuser password) & tick the save box.

Note: If you forgot the password, you're out of luck. Uninstall the software and try again but, this time, write it down.

Now, in pgAdmin III, expand the database server tree by clicking the plus-sign.

Down the bottom, you will see a user called "postgres".

Caution! Do not modify the "postgres" user. This is the default administrator of all the postgre databases. It will be used during ADempiere server setup where you will need to enter the login for this user.

Right click on "Login Roles" and create a new user. In the Properties tab, create the user "adempiere" with a password "adempiere". (You can/should change this to something more secure later.) In the Role Privileges tab, uncheck Inherit Rights from parent roles and check Superuser and all boxes below Superuser.

Now return to Database at the top and right click. Select create database. Name it "adempiere" and select the owner "adempiere" and encoding "UTF8" (see image below). Leave all the other variables blank.

Note: If you installed PostgreSQL 8.2.1 (or earlier) without PL/Java then Skip to the bottom for additional info.

Load the Initial Adempiere Database Data

Open a DOS shell with Start Button / Run / Open: cmd

Navigate to C:\Adempiere\data

Run the following command:

psql -U adempiere -d adempiere -f Adempiere_pg.dmp >> dump_errors.log

Note: You will be prompted for the password for the adempiere user for each command.

This command imports the ADempiere database. This is critical as you can not setup the application without it.

The import will take a few minutes to run and there should be no errors. If you observe errors, you can find out what went wrong by inspecting the file dump_errors.log

Note: If you are restoring or duplicating an installation, you can replace Adempiere_pg.dmp with ExpDat.dmp - the database export file from the original installation. The software versions should be the same or you will have to apply database migration scripts to bring the database to the same version as the software.

Migrate the Database

Common Reasons for errors during setup

• Make sure you follow every instruction exactly because there are many small details that must be correct!
• Error on JDK: install JDK (the JRE is not sufficient!)
• If you change your Java then make sure you change the Environmental Variables JAVA_HOME, JRE_HOME, the two (or three) references in PATH, and the RUN_setup.bat "Java Home"
• Web Port: probably port 80 is already used by other web server. You can use something like 8080 or 8088 (and correspondingly 8443 for the secure port)
• If you get "Error Database Port (DB Server Port = 5432)", change the 'Database Server' from <your-computer-name> to localhost. The alternative is to use a fixed IP address on your server or desktop and put this address in the Database Server, or if you have a laptop then you need to install a loopback adapter
• If you move the Adempiere directory (or update Adempiere) after already executing RUN_setup.bat, then you should delete the file adempiere.properties in C:\Documents & Settings\<your-user-name>
• If you did not include in your path C:\Program Files\PostgreSQL\8.3\bin , then at Step 7 you will need to replace the psql command with:

International Version

C:\"Program Files"\PostgreSQL\8.3\bin\psql

Italian Version

C:\Programmi\PostgreSQL\8.3\bin\psql

German Version

C:\Programme\PostgreSQL\8.3\bin\psql