Commerce

8.3.x

Setting up Developer Environment

Configuring Environment Variables

Use this procedure to set system environment variables for:

  • Java: JAVA_HOME and JAVA_OPTS
  • Maven: MAVEN_HOME and MAVEN_OPTS

Windows

  1. Open the Start menu, right-click My Computer and select Properties.

  2. Click Advanced System Settings.

    Windows System Settings - Advanced

    To quickly show the System Properties > Advanced > Environment Variables from the Windows Run prompt, type SystemPropertiesAdvanced and press Enter.

  3. In the System Properties > Advanced, click Environment Variables. Environment Variables button in Windows System Properties window

  4. To add a new system environment variable, on the Environment Variables window, click New.

  5. Add the following:

    • JAVA_HOME: C:\Program Files\Zulu\zulu-8-amd64
    • JAVA_OPTS: -Xmx1024m -Dsun.lang.ClassLoader.allowArraySyntax=true
    • MAVEN_HOME: C:\apache-maven-3.6.2
    • MAVEN_OPTS: -Xmx2548m -XX:ReservedCodeCacheSize=128m -Dsun.lang.ClassLoader.allowArraySyntax=true

    The values for the JAVA_HOME and MAVEN_HOME variables depend on the location where Java and Maven are installed. This location might differ from the default values provided.

  6. Select the Path system variable, and click Edit.

  7. Add the following variables at the end of the Path variable:

    ;%JAVA_HOME%\bin;%MAVEN_HOME%\bin;

Mac and Linux

  1. Modify your ~\.bash_profile (if using Bash shell) or ~\.zshrc (if using zsh shell) in your home folder to set the required environment variables.

    export JAVA_HOME=$(/usr/libexec/java_home -v "1.8.0")
export JAVA_OPTS="-Xmx1024m -Dsun.lang.ClassLoader.allowArraySyntax=true"
export MAVEN_HOME=/home/USERNAME/tools/apache-maven-3.6.2
export MAVEN_OPTS="-Xmx2548m -XX:ReservedCodeCacheSize=128m -Dsun.lang.ClassLoader.allowArraySyntax=true"
export PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin

  2. Open a new terminal window and verify the installation as follows:

    $ java -version
openjdk version "1.8.0_275"
OpenJDK Runtime Environment (Zulu 8.50.0.51-CA-macosx) (build 1.8.0_275-b01)
OpenJDK 64-Bit Server VM (Zulu 8.50.0.51-CA-macosx) (build 25.275-b01, mixed mode)

$ mvn -version
Apache Maven 3.6.2 (40f52333136460af0dc0d7232c0dc0bcf0d9e117; 2019-08-27T08:06:16-07:00)
Maven home: /Users/gdenning/apache-maven-3.6.2
Java version: 1.8.0_275, vendor: Azul Systems, Inc., runtime: /Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home/jre
Default locale: en_CA, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.7", arch: "x86_64", family: "mac"

Building Source Code

Checkout Source Code

Windows File Path Limitation

Do not save your source project to a directory if the file path is greater than 20 characters. Windows file paths are limited to 260 characters. The longest file path in the source code is greater than 230 characters.

To checkout a local copy of the Elastic Path source code from your source control repository:

  1. Create a folder to save the Elastic Path source.
  2. Checkout the Elastic Path Commerce code from the source control repository to your local source folder.

Configure Maven settings.xml

Before you build the source code, create a local Maven directory and update the settings.xml file.

  1. Create an .m2 directory in your local user directory. Example: > mkdir C:\Users\<YourWindowsUser>\.m2

  2. Copy the settings.xml file from the branch location ../extensions/maven to your local directory .m2.

  3. Edit the following values in the settings.xml file to match your local developer environment.

    SettingDescription
    epdb.reset_userMaven Profile: mysql-dev-db. The database account with administrative permissions that can drop and create databases and users in your local database.
    epdb.reset_passwordMaven Profile: mysql-dev-db. The password for epdb.reset_user.
    ep.local.asset.pathThe path to your local /extensions/assets/ext-assets/src/main/assets source directory.
    ep.smtp.hostYour SMTP Server.
    internet-mirrorThe URL of your organization’s Nexus server. Verify that the URL is already set. If not, contact the person who set up the team environment. For more information, see Configure the Maven Settings for the Team.
    warning

    If these property values do not exist in the settings.xml file, the source code might not be following the guidelines at Setup Guide, and you cannot build and deploy the Elastic Path Web Applications.

Build All Projects

You can build all projects with one Maven command.

  1. Open the command line and navigate to the Elastic Path Commerce source directory.

  2. Run the following Maven command:

    mvn clean install -DskipAllTests

    With the -DskipAllTests command, the system does not run any unit test or integration tests, however the system still builds the test. For more details on the Maven arguments, see Elastic Path Maven Commands.

Build Individual Modules

You can also build each module in Elastic Path separately, if required. However, you cannot build the individual modules unless you build the Elastic Path Commerce source directory at least once. When you build the Elastic Path Commerce modules separately, you must follow the following order:

  • commerce-data
  • commerce-engine
  • health-monitoring
  • commerce-manager
  • cortex-resources
  • extensions

For example, when you build the commerce-manager module, you must first build the commerce-data and commerce-engine modules separately.

To build a modules individually, in the command line, navigate to the Elastic Path Commerce source directory.

  1. Navigate to the project/module that you want to build.

  2. Enter the following Maven command:

    mvn clean install -DskipAllTests

    With the -DskipAllTests command, the system does not run any unit test or integration tests, however the system still builds the test. For more details on the Maven arguments, see Elastic Path Maven Commands

Local Database Setup

Elastic Path Commerce supports multiple database engines. Depending on which engine you choose, you will want to setup the corresponding database on your local development environment. Follow the steps in the appropriate section below.

MySQL

  1. In a command prompt, run the shell command below to download and run the MySQL docker image.

    For MySQL 5.7:

    docker run --name mysql-57-db --env="MYSQL_ROOT_PASSWORD=mysecretpassword" -p 3306:3306 -d mysql:5.7 --transaction_isolation=READ-COMMITTED --lower_case_table_names=1

    For MySQL 8.0:

    docker run --name mysql-80-db --env="MYSQL_ROOT_PASSWORD=mysecretpassword" -p 3306:3306 -d mysql:8.0 --transaction_isolation=READ-COMMITTED --lower_case_table_names=1
    note

    It is recommended to change mysecretpassword to something more secure.

  2. Edit your ~/.m2/settings.xml:

    1. In the <activeProfiles> section uncomment mysql-dev-db and comment out all other profiles ending with -dev-db.
    2. Check the mysql-dev-db profile definition and ensure that epdb.reset_password is set to the password you defined when starting the Docker image.

  3. Browse to your Elastic Path Commerce repo, open folder extensions/database and run the following command: mvn clean install -Preset-db.

Ensure that your MySQL installation meets the following requirements:

  • MySQL runs in the READ_COMMITTED isolation level.
  • MySQL server time zone is set to UTC.

If these settings are not set, you will receive an error message similar to the following examples:

  • Isolation level error:

    The database transaction isolation must be `READ_COMMITTED` but it is `REPEATABLE_READ`.

  • MySQL server time zone error:

    The server time zone value `PDT` is unrecognized or represents more than one time zone.

Oracle

  1. Navigate to the Oracle Container Registry.

  2. Click on "Database", then “enterprise“.

  3. Accept the license terms on the right side top. Sign-in is required.

  4. Ensure that Docker is installed and running on your local machine.

  5. In a command prompt, run the shell commands below to login, download, and run the docker image. Notice that we set the parameter ORACLE_PWD - feel free to change this as required.

    docker login -u <email> -p <password> container-registry.oracle.com
docker run -d -it --name oracle-19-db -p 1521:1521 -e ORACLE_PWD=Oradoc_db1 container-registry.oracle.com/database/enterprise:19.3.0.0

  6. Ensure that oracle is running on docker using docker ps -a. You should see a contained named oracle-19-db.

  7. To view the docker logs, run docker logs oracle-19-db.

  8. Download and install the SQLDeveloper application.

  9. Use following default credentials to connect to your Oracle database from SQL Developer:

    • Username: sys
    • Password: Oradoc_db1
    • Hostname: localhost
    • Port: 1521
    • SID: ORCLCDB
    • Role: SYSDBA

  10. Execute the following SQL to create user C##EPDBUSER for connecting from EP apps:

    CREATE USER C##COMMERCEDB PROFILE DEFAULT IDENTIFIED BY ep
DEFAULT TABLESPACE USERS
TEMPORARY TABLESPACE TEMP
QUOTA UNLIMITED ON USERS ACCOUNT UNLOCK;

GRANT CONNECT, CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE TO C##COMMERCEDB;
GRANT EXECUTE ON DBMS_XA TO C##COMMERCEDB;
GRANT SELECT ON PENDING_TRANS$ TO C##COMMERCEDB;
GRANT SELECT ON DBA_2PC_PENDING TO C##COMMERCEDB;
GRANT SELECT ON DBA_PENDING_TRANSACTIONS TO C##COMMERCEDB;

  11. Modify the oracle-dev-db profile in your Maven settings.xml as specified below.

     <profile>
     <id>oracle-dev-db</id>
     <properties>
         <data.population.environment>local</data.population.environment>
         <epdb.host>localhost</epdb.host>
         <epdb.port>1521</epdb.port>
         <epdb.schemaname>C##COMMERCEDB</epdb.schemaname>
         <epdb.databasename>ORCLCDB</epdb.databasename>
         <epdb.username>C##COMMERCEDB</epdb.username>
         <epdb.password>ep</epdb.password>
         <epdb.reset_user>sys as sysdba</epdb.reset_user>
         <epdb.reset_password>Oradoc_db1</epdb.reset_password>
         <epdb.default.tablespace>USERS</epdb.default.tablespace>
         <epdb.temporary.tablespace>TEMP</epdb.temporary.tablespace>
         <epdb.params>?oracle.net.disableOob=true</epdb.params>
     </properties>
 </profile>

  12. Edit your ~/.m2/settings.xml:

    1. In the <activeProfiles> section uncomment oracle-dev-db and comment out all other profiles ending with -dev-db.
    2. Check the oracle-dev-db profile definition and ensure epdb.reset_password is set to the password you defined when starting the Docker image.

  13. Browse to your Elastic Path Commerce repo, open folder extensions/database and run the following command: mvn install -Preset-db.

PostgreSQL

A PostgreSQL database server can contain one or more named databases. Each database can contain one or more named schemas, which in turn contain tables. The Data Population tool will initialize a schema, but a database needs to be manually created first, using the instructions below.

  1. In a command prompt, run the shell command below to download and run the PostgreSQL docker image.

    docker run --name postgresql-14-db --env="POSTGRES_PASSWORD=mysecretpassword" -p 5432:5432 -d postgres:14 -c max_connections=1000
    note

    It is recommended to change mysecretpassword to something more secure.

  2. Download and install pgAdmin.

  3. Use following default credentials to connect to your PostgreSQL database from pgAdmin:

    • Username: postgres
    • Password: The password you defined when starting the Docker image.
    • Hostname: localhost
    • Port: 5432

  4. Create a new "Login/Group Role" with name epDbUser, password epDbPassword, and the Can login privilege.

  5. Create a new database with name COMMERCEDB.

  6. Edit your ~/.m2/settings.xml:

    1. In the <activeProfiles> section uncomment postgresql-dev-db and comment out all other profiles ending with -dev-db.
    2. Check the postgresql-dev-db profile definition and ensure that epdb.reset_user is set to postgres and epdb.reset_password is set to the password you defined when starting the Docker image.

  7. Browse to your Elastic Path Commerce repo, open folder extensions/database and run the following command: mvn clean install -Preset-db.

Last updated on 6/1/2024
← RequirementsPopulating Database →