Developer Setup Guide

This readme documents the setup process for a JMC developer for version 6 and above.

Prerequisites

1. Install Node.js v18.
2. Install java 17 JDK

Installing Node.js v18

For macOS

The recommended way to install node for use with commerce on macOS for use with is to use nvm. nvm will help manage multiple versions of node installed on your development machine. This is useful when you need to revisit branches/releases of Commerce that are still using Angular 7/Node 10. Installation instructions for nvm are provided on their GitHub README, but you may also just use homebrew to install (brew install nvm; remember that brew will ask you to add 2 lines to your shell profile ~/.zshrc).

Once fully installed and your shell is reset, you may run the following commands:

> nvm install 18
> nvm alias default 18

You may optionally install node 10 if you need to work on older branches/releases of commerce:

> nvm install 10

# from now on you may switch your current shell to use a different version like: 
> nvm use 10

If you do not want to use nvm, you may install Node.js via. homebrew or manually. These options may require you to manually deal with version incompatibilities if you need to work on an older branch/release that requires Node.js 10. * Homebrew: brew install node@18 * Manually: latest-v18

For Windows

Windows is very similar to the macOS installation except the tools are different: * nvm-windows * Your preferred package manager: chocolatey, scoop, or winget * Manually: nodejs.org

Terminology

• JMC - Jumpmind Commerce

Development Setup Server

• Checkout https://github.com/Jumpmind/commerce
• (Remove any old .ipr or .iws files in the commerce directory)
• Open IntelliJ
• Open the commerce folder in IntelliJ
  • You should have all the projects available in the Project explorer tab in IntelliJ
  • Open the Gradle Tools (View>Tool Windows>Gradle) and right click on the root 'jmc' folder and click 'Reload Gradle Project'
• Build > Build Project will build anything that has recently changed (the first time you build it will take a bit because the client needs to be built as well)
• Build > Rebuild Project will rebuild everything from scratch (including the client)
• Run/Debug the "Commerce Base (H2)" shortcut to run the server
• Hit http://localhost:6140 to bring up the application
  • If this is the first time you have run the application you will be prompted to personalize the device.
  • For a manager login, the User Id is 1111, and the Password is 1111. For an employee, it is 2222 for both Id and Password.
• Hit http://localhost:6140/sql to bring up a database explorer
  • The H2 path is <commerceProjectRoot>/headless/point-of-sale/base/work/DEMODB
  • User name: sa. Leave password blank.
• Hit http://localhost:6140/swagger-ui/ to browse the available services
• See Running with Postgres if needed

Build Errors

Below is a list of potential build errors you might encounter and how to fix them.

For Mac

If you counter the following error from protoc-gen-grpc-java:

Execution failed for task ':state-relay:protos:generateProto'.
> protoc: stdout: . stderr: /Users/andyblubaugh/.gradle/caches/modules-2/files-2.1/io.grpc/protoc-gen-grpc-java/1.60.1/34d30118bab14b74971d0c18c8d73ebd658039ca/protoc-gen-grpc-java-1.60.1-osx-aarch_64.exe: program not found or is not executable
  Please specify a program using absolute path or make sure the program is available in your PATH system variable
  --grpc_out: protoc-gen-grpc: Plugin failed with status code 1.

then install Rosetta with the command

softwareupdate --install-rosetta

Client Development Setup

The following are steps to setup the development environment for Commerce Angular Client.

1. You first need to have a local version of client/projects/core-kit built. Run the following commands to compile the library locally:

   > cd client
   > npm install
   > npm run develop-core
   

   The result will monitor for core changes and rebuild.

2. Start the client development server:

   > cd client
   > npm run develop-pos
   

3. Open Chrome to http://localhost:4200; NOTE: If this is the first time you have run the application you will be prompt to personalize the device.

How to Open a Pull Request

Below are the steps used to open a Pull Request. * Create a JIRA ticket for the documentation update * Create a new branch: chore|fix|bug/JMC-XXX (The JIRA ticket number) * Create a PR with chore|fix|bug: JMC-XXX: this is the description * Once done, post a link to the PR in the dev-commerce slack channel or directly send it to a code owner to get their approval on it.

The JIRA ticket types are as follows: * Release Bugs - usually created by QE during release testing * Production Bugs - usually created by Mike's team for bugs found by customers * Tasks - for architectural type improvements * Stories - Usually created by BAs (kevin and bella) for new features

For chores like documentation updates, a JIRA ticket is typically not needed, and you would use JMC-XXX for the JIRA ticket number

Some notes

1. npm run build - this builds the core libraries first. Always a good idea to do this when you switch branches or are starting a new task

   a) npm run build has all the dependent projects in their correct order so it should be able to get a baseline of all the libraries that are needed just for point of sale. 3. if core-kit development is being done, npm run develop-core is necessary 4. if point-of-sale-ui development is being done npm run develop-pos 5. if clienteling, inventory, or shopkeeper are being worked on, they would run the develop- command for each of those as well

Running with Postgres

Short version

• run docker compose up from the root or use the Commcerce DB (Postgres) run configuration
• run any of the Commerce run configurations (ie Commerce Base ...) as you normally would, except choose the ... (Postgres) version

Prerequisites

If docker is already installed:

• Docker Desktop - check the version in Docker Desktop at the bottom right of the window
• Docker CLI + Compose v2, BuildX Plugins (not necessary if using docker desktop) - run the following:

  echo "Docker CLI:    $(docker version --format '{{.Client.Version}}')"  
  echo "Docker Engine: $(docker version --format '{{.Server.Version}}')"  
  echo "Compose:       $(docker compose version --short)"
  echo "BuildX:        $(docker buildx version)"
  

Compare your versions against the minimum requirements below. These include a stable version of Compose v2, which is required if you: - use IntelliJ’s bundled Docker plugin with Compose run configurations - use docker compose (the modern syntax) instead of the older docker-compose

Recommended Versions

• Docker Desktop v4.10.0+
• includes stable compose v2
• includes CLI
• brew install --cask docker
• Docker CLI v20.10.17+ w/ Docker Compose v2 & Docker BuildX Plugins
• used when Docker is installed standalone (e.g., via Homebrew on macOS)
• see Colima + Docker below for mac/homebrew installation instructions

Starting docker and postgres

1. Start docker
2. Start docker services / dev environment, either:
   • IntelliJ: run the Commerce DB (Postgres) configuration
   • Terminal: run docker compose up -d from the root of the repo

Running the application

• Run a Commerce ... (Postgres) application run configuration (typically, this will be Commerce Base (Postgres))
• As needed, run any of the other Commerce ... (Postgres) configurations for microcaps, corp, businessunit, etc
• If you don't see these, you may need to sync gradle

Connecting to postgres (optional)

• Connect to the postgres data source via intellij (optional, but useful)
• Open the IntelliJ Database tool
• Select new/+ -> data source -> PostgreSQL
• settings:
  • host: localhost
  • port: 5432
  • user: pguser
  • password: pgpassword
  • database: jmc_base (general / default) | jmc_corp | jmc_businessunit
  • url: should autopopulate
• check the bottom of the window for "Install Missing Drivers" (and install if needed)
• save the connection
• Access postgres via terminal (optional, as needed)
• docker exec -it jmc_pg psql -U pguser

Stopping the application / services

When finished developing, and after stopping any Commerce applications or services, it is not necessary to stop docker services each time. It may be convenient to leave it running between application run/debug sessions just to save an extra step, provided you don't require a fresh database. Stopping docker services will not delete any database data given the current configuration, so it is safe to do so if you need to free up resources, at the end of the day, etc.

To stop docker services, either: - IntelliJ: If you used the Commerce DB - (Postgres) run config, open the Services tool, find and select the running docker-compose, then click Down - Terminal: Otherwise, if you used the terminal, run docker compose down from the root of the repo

Deleting the database

• Full Refresh / Start Fresh (common option):
• stop docker services
• delete the jmc_jmc_pg volume
• this deletes everything, including all data from Base, Corp, and BusinessUnit databases
• Single DB: (use if you don't want to lose data from the other DBs)
• with docker services running, run the following script

  # replace base with corp, businessunit, etc as needed
  docker exec jmc_pg psql -U pguser -c "drop database if exists jmc_base;"
  docker exec jmc_pg psql -U pguser -c "create database jmc_base;"
  

• IntelliJ's data source tool will sometimes act finicky if you delete and recreate a single db. If no schema/tables appear after deleting, recreating, and running an application, open the data source properties, navigate to the schemas tab, and 'fully' check the box next to the applicable database.

Troubleshooting docker / postgres issues

Docker Compose Compatibility Issues

• When running docker services via the IntelliJ run config, if you see an error like docker compose -f ... unknown shorthand flag ..., it's likely a form of incomplete docker version upgrade, and you might need to:
• uninstall docker
• delete anything docker-y from /usr/local/bin
• reinstall docker
• open docker desktop (if applicable)
• check the notifications bell for anything that needs to be 'repaired' and repair it
• this should ensure you're on the latest/desired version

Missing Database

• When attempting to run a program / run config, and given a correctly initialized container & postgres instance, if a required database does not seem to exist, it is likely that the application you are running requires a database that was added to the 01-create-databases.sql script since the postgres instance was first initialized. There are a couple ways to correct this:
• Follow the steps above for Deleting the database -> Full Refresh / Start Fresh, then attempt to run the application again (this will destroy all existing data)
• Connect to postgres via the terminal and create the necessary database (this will preserver other existing data)

Installing Docker

Mac + Docker Desktop

Options: - homebrew

brew install --cask docker-desktop

- https://docs.docker.com/desktop/setup/install/mac-install/

Note: if you are upgrading or had a previous docker installation that has since been removed, see Docker Compose Compatibility Issues

Mac + Colima

minimal, open source, free incl commercial usage

• install stuff and start colima

• note: brew install docker-compose may look like it's related to the old docker-compose (v1) syntax, but it's just the homebrew package name. It installs the current Compose v2+ plugin, which enables the modern docker compose syntax / cli plugin.

  brew install colima docker docker-compose docker-buildx
  colima start
  

• follow the homebrew caveats: add the below to ~/.docker/config.json (create if needed)

  {
    "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
    ]
  }
  

• verify

  colima version
  docker version
  docker compose version
  docker buildx version
  

• configure buildx as default - add this to your ~/.zprofile / ~/.zshrc / wherever you prefer to set these

  # docker
  export DOCKER_BUILDKIT=1
  docker buildx use colima 2>/dev/null || true
  

• lifecycle

  colima start # starts colima vm / similar to starting docker desktop
  colima start --edit # edit current profile config (cpu, mem, disk, etc)
  colima status # show whether colima is running and basic resource info
  colima stop # stops colima vm / similar to quitting docker desktop
  

• docker usage with colima running

  docker compose up # use docker as usual, colima acts as the vm/backend
  

• configure intellij plugin / integration

• Open IntelliJ Docker Settings (Settings > Build... > Docker)
• uncheck "Detect Docker executable automatically"
  • set both paths to /opt/homebrew/bin/docker
• set "Connect to Docker daemon with" → colima
• you should now see docker under IntelliJ's services tool/window
• you can run from there or navigate to the desired compose.yml and use the "play buttons" in the sidebar

Configuring gcloud for docker

Optional; required if pulling from our artifact registry

• install gcloud-cli and authenticate

  brew install gcloud-cli
  gcloud auth login
  

• if using docker cli only (with colima, etc)

  gcloud auth configure-docker us-east5-docker.pkg.dev # confirm hostname if this is unsuccessful