Skip to content

Local Setup

Jump to bottom
Yasin edited this page May 14, 2024 · 6 revisions

Setting Up Local Deployment for the FEGA-Norway Project

Welcome to the setup guide for local deployment on the FEGA-Norway project. This comprehensive guide is tailored to assist both new and experienced developers in establishing a robust development environment. Our goal is to facilitate a seamless and efficient setup process for you.

Prerequisites

Before you begin, it's crucial to have the following tools and languages installed on your system:

  1. Java 21: The primary programming language used in the project.
  2. Go 1.21: Essential for working with specific GoLang modules.
  3. Docker & Docker Compose: A key tool for creating isolated environments and running various services.
  4. Make sure you have at least 8GiB of free space on your machine.

Recommended Development Tools

These tools are not mandatory but can significantly enhance your development experience:

  1. Gradle CLI: A powerful tool for managing compilation and build processes.
  2. IntelliJ IDE (or alternatives): While IntelliJ is highly recommended for Java development, alternatives like VSCode, Emacs, or NeoVim can also be effective. The choice of IDE is a matter of personal preference and workflow compatibility. The Gradle build tool ensures a consistent build process regardless of the IDE used.

Detailed Java Installation Guide

Linux

  • We primarily use the Temurin variant of the JDK. However, other JDK variants from different vendors should work similarly.
  • Installation instructions for Temurin can be found here.

MacOS

  • Most JDK vendors provide easy-to-use installers for macOS.
  • For Homebrew users, install the latest JDK using: 
    brew install --cask temurin

Alternatively, MacPorts or direct installer downloads from JDK vendors are also viable options.

Also, ensure that the JAVA_HOME points to the correct version of JDK in your environment variables.

Windows

  • Windows users can download JDK installers directly from vendor websites.
  • For WSL (Windows Subsystem for Linux) users, follow the Linux installation instructions. Tip: Tools like asdf and SDKMan! are excellent for managing multiple Java versions. Their documentation offers detailed installation and usage instructions.

Setting Up Go

Follow the official Go installation guide, which provides detailed instructions for all operating systems. You can find it here.

Docker and Docker-Compose

While Docker isn't required for building the monorepo, it's essential for orchestrating the microservices. Find comprehensive installation guides for Docker tailored to your operating system and architecture here.

Running the setup

This orchestration setup only supports Linux and macOS.

To start the orchestration

# Navigate to the project root first.
./gradlew start-docker-containers

To stop the orchestration

# Navigate to the project root first.
./gradlew stop-docker-containers

Deploy changes of modules

Scenario 1: Say for example you modified a component in services/:

  1. Build the sub-module first. i.e., ./gradlew :services:tsd-api-mock:assemble
  2. Navigate into e2eTests folder
  3. Run docker compose up -d tsd (It will deploy the new component)

Here's the reference. Additionally, you can take a look at the docker-compose.template.yml file.

Module name Compose service name
tsd-api-mock tsd
mq-interceptor interceptor
localega-tsd-proxy proxy

Scenario 2: You modified a library located in lib/ folder (say: clearinghouse)

  1. Find the affected services/modules within the project.
  2. Assemble the lib. i.e., ./gradlew :lib:clearinghouse:assemble
  3. Also, assemble ./gradlew :services:localega-tsd-proxy:assemble
  4. Navigate into e2eTests folder
  5. Run docker compose up -d proxy (It will deploy the new component)

Troubleshooting

If the orchestration fail to start for some reason. We suggest trying the fixes below.

I have conflicting containers. How do I remove them?

If for some reason it complaints about conflicting container names, we suggest you manually remove those.

docker rm tsd db mq proxy interceptor postgres ingest verify finalize mapper doa cegamq cegaauth
Docker complaints about port issues when running

The following ports must be free when running the setup. 5432 5672 5433 80 5673 15672 25672 if any other service is running please make sure you stop them or map the service ports in the docker-compose.template.yml file to different ones to match your needs.

I made changes in `services/` but when I run latest are not there in the build

Try removing the stale images.

docker rmi tsd-proxy:latest tsd-api-mock:latest mq-interceptor:latest --force
I have `docker-compose` but I can't find `docker compose` command?

In some cases, particularly on older Ubuntu distributions, you might find that you have docker-compose (V2) installed but not the docker compose subcommand. To resolve this, first ensure you have Compose V2 and then, you can create a symbolic link in the cli-plugins directory by executing the following commands:

mkdir -p ~/.docker/cli-plugins
ln -sfn $(which docker-compose) ~/.docker/cli-plugins/docker-compose

For migration guidance to Docker Compose, visit migrate to docker compose. Also, for further discussions and troubleshooting, refer to the GitHub issue at https://github.com/docker/compose/issues/8630.

Docker fails to build mq-interceptor (dial tcp: lookup proxy.golang.org: i/o timeout)

Do a docker daemon restart.

I made a mess. I want to start from scratch.

First, clean the e2eTests directory and all the submodules.

sudo rm -rf e2eTests/tmp e2eTests/bin docker-compose.yml && ./gradlew clean

Stop the running containers:

docker stop tsd db mq proxy interceptor postgres ingest verify finalize mapper doa cegamq cegaauth

Remove the stopped containers:

docker rm tsd db mq proxy interceptor postgres ingest verify finalize mapper doa cegamq cegaauth --force

Remove the stale images:

docker rmi tsd-proxy:latest tsd-api-mock:latest mq-interceptor:latest --force

And then finally, restart the Docker Daemon.

Clone this wiki locally