Skip to content

development.md

Latest commit

 

History

History
154 lines (99 loc) · 6.37 KB

development.md

File metadata and controls

154 lines (99 loc) · 6.37 KB
Raw

Development Guide

This document describes how to develop and add features to the CCI Bank Corp application in your local environment.

Prerequisites

Access to SE team CERA plaform.

OR

Access to a forked / branched cluster.

Skaffold will use whatever context is active for kubectl

Install Tools

You can use MacOS or Linux as your dev environment - all these languages and tools support both.

  1. Docker Desktop
  2. kubectl (can be installed separately or via gcloud)
  3. skaffold 1.27+ (latest version recommended)
  4. OpenJDK 17 (newer versions not tested)
  5. Python 3.7+
  6. piptools

Installing JDK 17 and Maven 3.8

If your package manager doesn't allow you to install JDK 17 or Maven 3.8 (for example, if you're on an older version of Ubuntu), you can follow the following instructions.

Find the latest release of JDK 17 and extract it to the /opt directory:

wget https://download.java.net/java/GA/jdk17.0.1/2a2082e5a09d4267845be086888add4f/12/GPL/openjdk-17.0.1_linux-x64_bin.tar.gz
tar xvf openjdk-17.0.1_linux-x64_bin.tar.gz
sudo mv jdk-17*/ /opt/jdk17

Maven 3.8 is included using the maven wrapper pattern. All maven commands should use the mvnw executable in root of this project.

i.e. mvn test becomes ./mvnw test

This ensures all team members and CI builds get conistent results.

If you have multiple versions of Java/Python you can create a profile containing the paths of the newly extracted JDK and Maven directories:

sudo tee /etc/profile.d/java.sh <<EOF
export JAVA_HOME=/opt/jdk17
export M2_HOME=/opt/apache-maven-3.8.5
export MAVEN_HOME=/opt/apache-maven-3.8.5
export PATH=\$JAVA_HOME/bin:\$M2_HOME/bin:\$PATH
EOF
sudo chmod +x /etc/profile.d/java.sh

Verify that the versions are correct:

source /etc/profile.d/java.sh
java -version
mvn -version

Adding External Packages

Python

If you're adding a new feature that requires a new external Python package in one or more services (frontend, contacts, userservice), you must regenerate the requirements.txt file using piptools. This is what the Python Dockerfiles use to install external packages inside the containers.

NOTE: Pip-tools is a lighter/faster tool compared to pipenv, and supported by pipenv maintainer. If we see need to switch we can.

To add a package:

  1. Add the package name to requirements.in within the src/<service> directory:

  2. From inside that directory, run:

python3 -m pip install pip-tools
python3 -m piptools compile --output-file=requirements.txt requirements.in
  1. Re-run skaffold dev or skaffold run to trigger a Docker build using the updated requirements.txt.

Java

If you're adding a new feature to one or more of the Java services (ledgerwriter, transactionhistory, balancereader) and require a new third-party package, do the following:

  1. Add the package to the pom.xml file in the src/<service> directory, under <dependencies>. You can find specific package info in Maven Central (example). Example:
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
        </dependency>
  1. Re-run skaffold dev or skaffold run to trigger a Jib container build using Maven and the updated pom file.

Testing your changes locally

We recommend you test and build directly on Kubernetes, from your local environment. This is because there are seven services and for the app to fully function, all the services need to be running. All the services have dependencies, environment variables, and secrets and that are built into the Kubernetes environment / manifests, so testing directly on Kubernetes is the fastest way to see your code changes in action. To avoid collisions you should use a SE specific namespace.

You can use the skaffold tool to build and deploy your code to the SE CERA Cluster on EKS.

NOTE: You must set docker to login to Nexus!

echo "${NEXUS_PASSWORD}" | docker login --username ${NEXUS_USERNAME} --password-stdin docker.nexus.cera.circleci-fieldeng.com

Nexus password can be created per SE. Admin creds in team vault.

Option 1 - Build and deploy continuously

The skaffold dev command watches your local code, and continuously builds and deploys container images to our cluster anytime you save a file. Skaffold uses Docker Desktop to build the Python images, then Jib (installed via Maven) to build the Java images.

# kubectl config use-context <CLUSTER_CONTEXT_TO_TARGET>
skaffold dev --default-repo=docker.nexus.cera.circleci-fieldeng.com -n MY_NAMESPACE

Option 2 - Build and deploy once

The skaffold run command build and deploys the services to our SE cluster one time, then exits.

skaffold run --default-repo=docker.nexus.cera.circleci-fieldeng.com -n MY_NAMESPACE

Running services selectively

Skaffold reads the skaffold.yaml file to understand the project setup. Here, it's split into modules that can be iterated on individually:

  • the backend module comprising of the five backend services.
  • the frontend module for the single frontend service.
  • the loadbalancer module for the single loadbalancer service.

**The setup mofule must prefix many of the modules. running -m setup,... should fix it.

To work with only the frontend module, run:

skaffold dev --default-repo=docker.nexus.cera.circleci-fieldeng.com  -m setup,frontend -n MY_NAMESPACE

To work with both frontend and backend modules, run:

skaffold dev --default-repo=docker.nexus.cera.circleci-fieldeng.com  -m setup -m frontend -m backend -n MY_NAMESPACE

Continuous Integration

Checkout .circleci/config.yml for CI steps