Skip to content

Commit e791f0c

Browse files
YATIN072007YATIN072007
committed
Docs: Add setup guide and execution logs documentation
- Create SETUP_GUIDE_AND_LOGS.md with step-by-step instructions for Linux, macOS, and Windows. - Document build prerequisites including apis-bom and apis-common installation. - Report Windows log findings and identify Vert.x version conflict. - Add template for reporting test results. Signed-off-by: YATIN JAMWAL <yatinjamwal07@gmail.com>
1 parent 710e9f2 commit e791f0c

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎SETUP_GUIDE_AND_LOGS.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Setup, Run, and Logging Guide for `apis-main`
2+
3+
This document provides step-by-step instructions to clone, build, run, and test `apis-main` on Linux, macOS, and Windows. It also includes instructions for capturing logs and a template for reporting results.
4+
5+
## 1. Prerequisites
6+
7+
Before starting, ensure you have the following installed on your system.
8+
9+
### All Operating Systems
10+
* **Java JDK 8 or 11+** (Target is Java 1.8).
11+
* Verify: `java -version`
12+
* **Maven 3.6+**.
13+
* Verify: `mvn -version`
14+
* **Git**.
15+
* Verify: `git --version`
16+
17+
---
18+
19+
## 2. Installation & Build Process
20+
21+
The `apis-main` project depends on `apis-bom` and `apis-common`, which must be built locally first.
22+
23+
**Commands (Run sequentially in your workspace directory):**
24+
25+
1. **Install `apis-bom`**:
26+
```bash
27+
git clone https://github.com/hyphae/apis-bom.git
28+
cd apis-bom
29+
mvn install
30+
cd ..
31+
```
32+
33+
2. **Install `apis-common`**:
34+
```bash
35+
git clone https://github.com/hyphae/apis-common.git
36+
cd apis-common
37+
mvn install
38+
cd ..
39+
```
40+
41+
3. **Build `apis-main` (This Repository)**:
42+
```bash
43+
# If not already cloned
44+
# git clone https://github.com/hyphae/apis-main.git
45+
cd apis-main
46+
mvn package
47+
```
48+
49+
**Capture Build Logs:**
50+
To save the build output to a file:
51+
```bash
52+
mvn package > build.log 2>&1
53+
```
54+
55+
---
56+
57+
## 3. Running the Application
58+
59+
The application is executed from the `exe` directory.
60+
61+
### Linux & macOS
62+
1. Navigate to the executable directory:
63+
```bash
64+
cd exe
65+
```
66+
2. Run the start script:
67+
```bash
68+
bash start.sh
69+
```
70+
* **macOS Note**: The script automatically detects runs on macOS (Darwin) and uses `cluster-mac.xml`.
71+
* **Capture Logs**: `bash start.sh > run.log 2>&1`
72+
73+
3. Stop the application:
74+
```bash
75+
bash stop.sh
76+
```
77+
78+
### Windows
79+
**Option 1: Git Bash (Recommended)**
80+
Use the Linux instructions above within a Git Bash terminal.
81+
82+
**Option 2: PowerShell**
83+
If you must use PowerShell, run the Java command manually:
84+
85+
1. Navigate to the executable directory:
86+
```powershell
87+
cd exe
88+
```
89+
2. Run the application:
90+
```powershell
91+
$jarPath = "../target/apis-main-3.0.0-fat.jar"
92+
java -Djava.net.preferIPv4Stack=true -Duser.timezone=Asia/Tokyo -Djava.util.logging.config.file=./logging.properties -Dvertx.hazelcast.config=./cluster.xml -jar $jarPath -conf ./config.json -cluster -cluster-host 127.0.0.1
93+
```
94+
3. Stop the application:
95+
Press `Ctrl+C` in the terminal window.
96+
97+
---
98+
99+
## 4. Testing
100+
101+
To run the unit tests:
102+
103+
```bash
104+
mvn test
105+
```
106+
107+
**Capture Test Logs:**
108+
```bash
109+
mvn test > test_results.log 2>&1
110+
```
111+
112+
---
113+
114+
## 5. Logs & Troubleshooting
115+
116+
### Where to Find Logs
117+
* **Standard Output**: Displayed in the terminal during execution.
118+
* **Log Files**: Created in the `exe` directory (configured via `logging.properties`).
119+
* `*.log`: General logs (e.g., `0.0.log`).
120+
* `*.err`: Error logs.
121+
122+
### Common Errors
123+
124+
**Error: `mvn: command not found`**
125+
* **Cause**: Maven is not installed or not in your system PATH.
126+
* **Fix**: Install Maven and ensure `mvn` works in a new terminal.
127+
128+
**Error: Dependency not found (`jp.co.sony.csl.dcoes.apis:apis-bom:pom:3.0.0`)**
129+
* **Cause**: You skipped step 2 (Installation). `apis-bom` and `apis-common` are not on Maven Central; they must be installed locally.
130+
* **Fix**: Clone and run `mvn install` for both `apis-bom` and `apis-common`.
131+
132+
**Error: Port in use (BindException)**
133+
* **Cause**: Another instance of `apis-main` is running.
134+
* **Fix**: Run `bash stop.sh` or manually kill the Java process.
135+
136+
---
137+
138+
## 6. Report Template (For GitHub Issue)
139+
140+
Use the following template to report your results for each OS.
141+
142+
```markdown
143+
# Local Setup & Test Report
144+
145+
## Summary
146+
| OS | Build Status | Run Status | Test Status | Notes |
147+
|---------|--------------|------------|-------------|-------|
148+
| Linux | [Untested] | [Untested] | [Untested] | |
149+
| macOS | [Untested] | [Untested] | [Untested] | |
150+
| Windows | **FAIL** | **FAIL** | **FAIL** | Critical Dependency Conflict (Vert.x 3 vs 4) |
151+
152+
## 1. Windows Execution Report
153+
154+
**Date**: 2026-02-02
155+
**Environment**: Windows, OpenJDK 21.0.8, Maven 3.9.6.
156+
157+
### Setup & Build
158+
* **Action**: Cloned `apis-bom`, `apis-common`, and `apis-main`. Built hierarchically.
159+
* **Observation**: `apis-bom` and `apis-common` built successfully (after ensuring versions aligned).
160+
* **Result**: `apis-main` compilation was successful.
161+
162+
### Test Execution
163+
* **Command**: `mvn test`
164+
* **Status**: **FAILURE**
165+
* **Error Log**:
166+
```text
167+
jp.co.sony.csl.dcoes.apis.main.app.ApisTest.testDeployAndUnDeploy -- Time elapsed: 0.395 s <<< ERROR!
168+
java.lang.IllegalStateException: No ClusterManagerFactory instances found on classpath
169+
at io.vertx.core.impl.VertxImpl.getClusterManager(VertxImpl.java:470)
170+
at io.vertx.core.impl.VertxImpl.<init>(VertxImpl.java:172)
171+
```
172+
* **Root Cause Analysis**:
173+
The `apis-main/pom.xml` specifies `vertx-core:3.7.1`.
174+
However, the current `apis-bom` (version 3.4.1) specifies `vertx-core:4.4.6`.
175+
`apis-common` (built against the BOM) uses Vert.x 4.x classes.
176+
When `apis-main` runs, it mixes Vert.x 3 (from its own POM) and Vert.x 4 (transitively from common/bom), causing the `ClusterManagerFactory` error because the SPI mechanism changed between versions.
177+
178+
### Run Execution
179+
* **Command**: `bash start.sh` (or equivalent java command)
180+
* **Status**: **FAILURE**
181+
* **Observation**: Application crashes at startup due to the same version mismatch/class loading errors.
182+
183+
### Recommendation for Maintainers
184+
1. **Update `apis-main` to use Vert.x 4.x** to match `apis-bom` and `apis-common`.
185+
2. Or, **Rollback `apis-bom`** to a version compatible with Vert.x 3.7.1 (likely v3.0.0 is needed, but was not found in tags).
186+
```

0 commit comments

Comments
 (0)