Commerce

8.5.x

Setting up Developer Environment

Prerequisites

  1. Install Development Tools.
  2. Clone the ep-commerce Git repository. For more information, see Source Code.

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-17-amd64
    • JAVA_OPTS: -Xmx2048m -Dsun.lang.ClassLoader.allowArraySyntax=true
    • MAVEN_HOME: C:\apache-maven-3.9.1
    • MAVEN_OPTS: -Xmx4000m -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 "17")
export JAVA_OPTS="-Xmx2048m -Dsun.lang.ClassLoader.allowArraySyntax=true"
export MAVEN_HOME=/home/USERNAME/tools/apache-maven-3.9.1
export MAVEN_OPTS="-Xmx4000m -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 "17.0.7" 2023-07-18 LTS
OpenJDK Runtime Environment Zulu17.44+15-CA (build 17.0.7+7-LTS)
OpenJDK 64-Bit Server VM Zulu17.44+15-CA (build 17.0.7+7-LTS, mixed mode, sharing)

$ mvn -version
Maven home: /Users/USERNAME/apache-maven-3.9.1
Java version: 17.0.7, vendor: Azul Systems, Inc., runtime: /Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
Default locale: en_CA, platform encoding: UTF-8
OS name: "mac os x", version: "13.4.1", arch: "aarch64", family: "mac"

  3. Optionally install jenv to allow easy switching between Elastic Path Commerce source code repos that require Java 8 or Java 17. Once this is installed, your machine will automatically use the correct version of Java based on the value found in the .java-version file in the source code repository.

    1. Add your JDKs to jenv as in the following example:

      jenv add /Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home/
jenv add /Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home/

    2. Enable the jenv plugins:

      jenv enable-plugin maven
jenv enable-plugin export

    3. Set Java 1.8 as your default:

      jenv global 1.8

    4. Run jenv doctor to ensure that everything is configured properly:

      jenv doctor

    5. Double-check that the versions are configured properly:

      jenv versions

Configure Maven settings.xml

With a Maven Repository Manager

A Maven repository manager is required for effective shared development. If your team has prepared the Maven repository manager then complete the below instructions to configure your settings.xml to use it. For more information about configuring a Maven repository manager, see Maven Repository Manager.

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 home directory. Example: mkdir ~\.m2

  2. Copy the settings.xml file from the extensions/maven folder of the ep-commerce source code to your ~/.m2 folder.

  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.hostThe host name of your 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 Update Maven Settings.
    warning

    If these property values do not exist in the settings.xml file then you may have issues locally building and deploying the Elastic Path Commerce Web Applications.

Without A Maven Repository Manager

If your team has not yet prepared the Maven repository manager then complete the below instructions to configure your settings.xml to define the repositories locally. For more information about configuring a Maven repository manager see Maven Repository Manager.

The extensions module in Elastic Path Commerce source contains a maven/individual-settings.xml that you can use if your Maven repository manager is not yet ready.

  1. Copy individual-settings.xml to ${user.home}/.m2 and rename it to settings.xml.

  2. Change EP_REPOSITORY_USER and EP_REPOSITORY_PASSWORD to the credentials used for connecting to the public Elastic Path Maven repository.

    <servers>
    <server>
        <id>ep-public</id>
        <username>EP_REPOSITORY_USER</username>
        <password>EP_REPOSITORY_PASSWORD</password>
    </server>
    <server>
        <id>ep-cortex</id>
        <username>EP_REPOSITORY_USER</username>
        <password>EP_REPOSITORY_PASSWORD</password>
    </server>
    <server>
        <id>ep-commerce-engine</id>
        <username>EP_REPOSITORY_USER</username>
        <password>EP_REPOSITORY_PASSWORD</password>
    </server>
    <server>
        <id>ep-accelerators</id>
        <username>EP_REPOSITORY_USER</username>
        <password>EP_REPOSITORY_PASSWORD</password>
    </server>
</servers>

  3. Make any changes required for your project environment.

Local IDE Setup

Elastic Path recommends that developers use the IntelliJ Idea IDE. Make sure that your version is 2023.3.0 or newer.

Setup Code Formatting

We recommend importing the Elastic Path code style, which ensures that formatted code follows our standard best practices.

Open "Settings", then navigate to "Editor" --> "Code Style". Click the gear icon beside the scheme, and choose "Import Scheme" --> "IntelliJ IDE code style XML". Then use the file browser to select the devops/code-style.xml from the ep-commerce source code.

IntelliJ Code Style import

Install Plugins

We recommend installing the following plugins:

  • Cucumber for Java
  • Gherkin

Follow these steps:

  1. In the IntelliJ menu, select "IntelliJ IDEA" --> "Settings".
  2. Navigate to "Plugins".
  3. Make sure that the plugins listed above are showing in the "Installed" tab. If not, search for them in the "Marketplace" tab and click "Install".
  4. Run "File" --> "Invalidate Caches..." --> "Invalidate and Restart".

Compiler Settings

You should change the default compiler settings in IntelliJ to disable deprecation warnings, as you will occasionally get errors while building.

Follow these steps:

  1. In the IntelliJ menu, select "IntelliJ IDEA" --> "Settings".
  2. Navigate to "Build, Execution, Deployment" --> "Compiler" -> "Java Compiler".
  3. Under the "Javac Options", uncheck "Report use of deprecated features".

Maven Settings

You should change the default Maven settings in IntelliJ to ensure that JDK 17 is being used, and Maven 3.9.2 or later is being used.

Follow these steps:

  1. In the IntelliJ menu, select "IntelliJ IDEA" --> "Settings".
  2. Navigate to "Build, Execution, Deployment" --> "Build Tools" -> "Maven".
  3. Set "Maven home path" to "Bundled (Maven 3)", which should set the "Version" field to 3.9.2 (or later).
  4. Navigate to "Importing" under the current node.
  5. Set "VM Options for importer" to "-Xmx3G".
  6. Set "JDK for importer" to "zulu-17".

Associate Feature File Type to Cucumber Scenario

Follow these steps:

  1. In the IntelliJ menu, select "File" --> "File Properties" --> "Associate with File Type..."
  2. Enter file pattern *.feature, and select "Cucumber Scenario" in the list.
  3. Click "OK".

Importing the Source

Follow these steps:

  1. In the IntelliJ menu, select "File" --> "Open...".
  2. Navigate to the root folder of the source to open, for example ~/git/ep-commerce.
  3. Click "Open".
  4. Wait for the project to finish loading and indexes to complete building.

Project SDK Settings

Make sure that IntelliJ is using the Java 17 JDK for internal builds. By default, IntelliJ may detect that the source is using Java 11, since the code compiles to Java 11 bytecode.

If IntelliJ is not configured properly, the Java classes will not resolve properly, and you see the following error message:

Unable to provision, see the following errors:

1) Error in custom provider, java.lang.TypeNotPresentException: Type org.eclipse.tycho.core.maven.TychoMavenLifecycleParticipant not present
  at ClassRealm[extension>org.eclipse.tycho:tycho-maven-plugin:4.0.0, parent: jdk.internal.loader.ClassLoaders$AppClassLoader@5c29bfd] (via modules: org.eclipse.sisu.wire.WireModule -> org.eclipse.sisu.plexus.PlexusBindingModule)
  while locating org.apache.maven.AbstractMavenLifecycleParticipant annotated with @com.google.inject.name.Named(value="TychoMavenLifecycleListener")

1 error

Follow these steps:

  1. Right-click on the root project (ep-commerce [commerce-parent]).
  2. Click "Open Module Settings".
  3. Navigate to "Project Settings" --> "Project".
  4. Change SDK to "zulu-17" (it will likely be set to "zulu-11").
  5. Then right-click on the root project pom.xml, and click "Maven" --> "Reload Project".

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.

Oracle

If you are running on an M1 or M2 Macbook, follow the Install Oracle (M1/M2 Mac only) instructions. For all other operating systems, follow the Install Oracle (Non-M1/M2 Mac and Windows) instructions.

Install Oracle (M1/M2 Mac only)

  1. Install Lima with HomeBrew:

     brew install lima

  2. Create a new Ubuntu Virtual Machine:

    limactl start

  3. A menu will appear. Select Open an editor to review or modify the current configuration. Using the editor, modify the following properties:

    arch: "x86_64"
memory: "8GiB"

  4. Save the file and exit the editor. Several files will be downloaded and installed.

    note

    If you run into a bug where Lima gets stuck on Waiting for the essential requirement 1 of 5: "ssh" for several minutes and then fails, follow these steps.

  5. Connect to the Lima VM console.

    lima

  6. In a command prompt, run the shell commands below to login, download, and run the Docker image. Replace <email> and <password> with your Oracle credentials. Also feel free to change the Oracle database password specified in ORACLE_PWD.

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

  7. Ensure that Oracle is running on Docker using nerdctl ps -a. You should see a container named oracle-19-db.

  8. The container may take several hours to start the first time. Monitor progress by viewing the Docker logs. Run nerdctl logs -f oracle-19-db. When the logs show DATABASE IS READY TO USE!, Oracle is started.

  9. Open a terminal window to the Docker container.

    nerdctl exec -it oracle-19-db bash

  10. Follow the steps in Set max_string_size to extended.

Install Oracle (Non-M1/M2 Mac and Windows)

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

  2. In a command prompt, run the shell commands below to login, download, and run the Docker image. Replace <email> and <password> with your Oracle credentials. Also feel free to change the Oracle database password specified in ORACLE_PWD.

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

  3. Ensure that Oracle is running on Docker using docker ps -a. You should see a container named oracle-19-db.

  4. The container may take several hours to start the first time. Monitor progress by viewing the Docker logs. Run docker logs -f oracle-19-db. When the logs show DATABASE IS READY TO USE!, Oracle is started.

  5. Open a terminal window to the Docker container.

    docker exec -it oracle-19-db bash

  6. Follow the steps in Set max_string_size to extended.

Set Max String Size to Extended

  1. In the terminal window, run the following commands:

    export ORACLE_SID=ORCLCDB
sqlplus sys/mysecretpassword as sysdba

  2. Within sqlplus, run the following commands to start the EXTENDED mode upgrade:

    ALTER SESSION SET CONTAINER=CDB$ROOT;
ALTER SYSTEM SET max_string_size=extended SCOPE=SPFILE;
SHUTDOWN IMMEDIATE
STARTUP UPGRADE
quit

  3. In the terminal, run the following commands to finish the EXTENDED mode upgrade for the containerized databases:

    cd $ORACLE_HOME/rdbms/admin
$ORACLE_HOME/perl/bin/perl $ORACLE_HOME/rdbms/admin/catcon.pl -u SYS --force_pdb_mode 'UPGRADE' -d $ORACLE_HOME/rdbms/admin -b utl32k_cdb_pdbs_output utl32k.sql
sqlplus sys/mysecretpassword as sysdba

  4. Within sqlplus, run the following commands to restart the database:

    SHUTDOWN IMMEDIATE
STARTUP
quit

  5. Run the following commands to finish the EXTENDED mode upgrade for the main database:

    cd $ORACLE_HOME/rdbms/admin
$ORACLE_HOME/perl/bin/perl $ORACLE_HOME/rdbms/admin/catcon.pl -u SYS --force_pdb_mode 'READ WRITE' -d $ORACLE_HOME/rdbms/admin -b utlrp_cdb_pdbs_output utlrp.sql

  6. Exit the Docker container.

    exit

  7. Follow the steps in Create ep-commerce schema.

Create ep-commerce schema

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

     <profile>
     <id>oracle-dev-db</id>
     <properties>
         <epdb.host>localhost</epdb.host>
         <epdb.port>1521</epdb.port>
         <epdb.databasename>ORCLPDB1</epdb.databasename>
         <epdb.username>C##COMMERCEDB</epdb.username>
         <epdb.password>ep</epdb.password>
         <epdb.reset_databasename>ORCLCDB</epdb.reset_databasename>
         <epdb.reset_user>sys as sysdba</epdb.reset_user>
         <epdb.reset_password>mysecretpassword</epdb.reset_password>
         <epdb.default.tablespace>USERS</epdb.default.tablespace>
         <epdb.temporary.tablespace>TEMP</epdb.temporary.tablespace>
     </properties>
 </profile>

  2. 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.

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

  4. (Optional) Download and install SQLDeveloper.

  5. (Optional) Use following default credentials to connect to your Oracle database from SQL Developer:

    • Username: C##COMMERCEDB
    • Password: ep
    • Hostname: localhost
    • Port: 1521
    • Service name: ORCLPDB1

Stop Lima (M1/M2 Mac Only)

Follow these steps to safely shut down Lima.

  1. Connect to the Lima VM console.

    lima

  2. Stop Docker.

    nerdctl stop oracle-19-db

  3. Exit the Lima VM console.

    exit

  4. Stop the Lima VM.

    limactl stop

Start Lima (M1/M2 Mac Only)

Follow these steps to start Lima again after you've completed the setup steps and previously stopped Lima.

  1. Start the Lima VM.

    limactl start

  2. Connect to the Lima VM console.

    lima

  3. Start the Oracle Docker image.

    nerdctl start oracle-19-db

  4. The container should start within a couple of minutes. Monitor progress by viewing the Docker logs. Run nerdctl logs -f oracle-19-db. When the logs show DATABASE IS READY TO USE!, Oracle is started.

  5. Exit the Lima VM console.

    exit

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 database with name COMMERCEDB.

  5. 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.

    3. epdb.schemaname is set to public by default. This can be changed to any other value.

      note

      PostgreSQL converts schema name string to lowercase regardless of the value specified.

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

Last updated on 11/1/2024
← Source CodeBuilding Elastic Path Commerce →