Guide for Local End-to-End Testing of hyphae APIS

[3akare]

Description

This issue documents a reproducible method for setting up, building, and running the complete suite of APIS services locally within a Docker container. This allows for a consistent end-to-end testing environment for all 17 repositories.

---

1. Environment Setup

The entire environment is containerised using Docker to ensure consistency and avoid host machine dependency issues.

1. Pull the base image:
   Start with a clean Ubuntu 20.04 LTS image.

   docker pull ubuntu:20.04

2. Run the container interactively:

   docker run -it --name apis-dev ubuntu:20.04

3. Install dependencies:
   Once inside the container's shell, install all the necessary packages for the project to build and run correctly.

   apt-get update && apt-get install -y \
       git \
       make \
       maven \
       groovy \
       python3-venv \
       python3-pip \
       mongodb

---

2. Clone and Build APIS

With the environment ready, clone the main APIS repository which contains the Makefile orchestrator.

1. Clone the main repo:

   git clone https://github.com/hyphae/APIS
   cd APIS

2. Build all services:
   The Makefile simplifies the process of cloning and building all required repositories. Run the master build command:

   make build

---

3. Configuration Fix: Standardize MongoDB Port

During testing, a port discrepancy was found. Some services expected MongoDB on port 27017, while others expected 27018.
Action Taken: All service configurations were standardized to use the default MongoDB port, 27017, to ensure seamless communication between all components.

-----

4. Running the Full Application Suite

Once the build is complete and configurations are harmonized, the application stack can be started.

1. Run all services:
   Use the Makefile to start MongoDB and all APIS services in the correct order.

   make run

2. Verify services:
   After running the command, you can interact with the web interface and the emulator through your host machine's browser.
   • APIS Web Interface: http://localhost:4382
   • Emulator Interface: http://localhost:4390

5. Persisting the Environment (Creating a Docker Image)

To avoid repeating the setup process, the configured container can be saved as a new Docker image.

1. Commit the container:
   Open a new terminal on your host machine and run:

   # Replace <container_id> with the ID of your 'apis-dev' container
   docker commit <container_id> hyphae-apis-stable:latest

2. Run the pre-built image:
   You can now run the entire pre-built application stack with a single command, mapping the necessary ports.

   docker run -it \
     -p 10000:10000 \
     -p 4382:4382 \
     -p 4390:4390 \
     -p 8000:8000 \
     -p 27017:27017 \ # Optional: Expose for a DB client like Mongo Compass
     hyphae-apis-stable:latest

3. Start services inside the new container:
   Once the container is running, navigate to the APIS directory and execute the run command.

   cd APIS
   make run

Pre-built Docker Image Link

For convenience, the final, working Docker image has been uploaded and can be accessed here:

docker push 3akare/hyphaes-stable:latest

[subhramit]

Nice work @3akare!
@axmsoftware I think this should go into our README doc?

[axmsoftware]

@3akare yes please. See also Issue#62, @AkarshSahlot had some suggestions. Thanks!