402 lines
20 KiB
Markdown
402 lines
20 KiB
Markdown
---
|
||
sidebar_position: 1
|
||
title: "Environment Setup Guide (TrizStock)"
|
||
description: "Complete guide to setting up the TrizStock development environment from scratch."
|
||
---
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Before You Start
|
||
|
||
Make sure you have the following before proceeding:
|
||
- **Local administrator rights** on your machine (required for most installations below)
|
||
- Access to our [Gitea instance](http://145.239.66.197:3000/).
|
||
- Your Gitea account credentials (request from your team lead if you don't have one yet)
|
||
- The application database credentials (request from your team lead — these are never stored in any repository)
|
||
|
||
# Overview of the Stack
|
||
|
||
| **Component** | **Version** | **Purpose** |
|
||
| ---------------------------- | ----------- | ------------------------------- |
|
||
| Java SE (JDK) | 8 | Runtime and compiler |
|
||
| Apache Maven | Any recent | Dependency management and build |
|
||
| Apache Tomcat | 9 | Java EE application server |
|
||
| Microsoft SQL Server | 2012 | Database engine |
|
||
| SQL Server Management Studio | Any recent | Database GUI client |
|
||
| NetBeans IDE | 17 | Development environment |
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 1 — Install Java SE Development Kit (JDK) 8
|
||
|
||
1. Download **JDK 8** from:
|
||
- [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/jdk-8u481-windows-x64)
|
||
- [Oracle's official archive](https://www.oracle.com/asean/java/technologies/javase/javase8u211-later-archive-downloads.html) if you have an account
|
||
2. Run the installer and complete the installation. Note the installation path (e.g., `C:\Program Files\Java\jdk1.8.0_xxx`).
|
||
3. Set the `JAVA_HOME` environment variable:
|
||
- Open **Start → Search → "Edit the system environment variables"**
|
||
- Click **Environment Variables**
|
||
- Under **System variables**, click **New**:
|
||
- Variable name: `JAVA_HOME`
|
||
- Variable value: `C:\Program Files\Java\jdk1.8.0_xxx` _(your actual JDK path)_
|
||
- Find the **`Path`** variable under System variables → click **Edit → New**, and add: `%JAVA_HOME%\bin`
|
||
- Click **OK** on all dialogs.
|
||
4. Open a **new** terminal window and verify:
|
||
```shell
|
||
java -version
|
||
javac -version
|
||
```
|
||
Both must return `1.8.x`. If `javac` is not found, `JAVA_HOME` or `PATH` was not set correctly.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 2 — Install Apache Maven
|
||
|
||
1. Download Maven from: _(Download the **binary zip archive**)_
|
||
- [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/apache-maven-3.9.15-bin)
|
||
- [Apache](https://maven.apache.org/download.cgi)
|
||
2. Extract it to a stable path with no spaces (e.g., `C:\dev\maven`).
|
||
3. Set environment variables:
|
||
- Create a new system variable:
|
||
- Variable name: `MAVEN_HOME`
|
||
- Variable value: `C:\dev\maven` _(your extraction path)_
|
||
- Add `%MAVEN_HOME%\bin` to the **`Path`** system variable (same way as Step 1).
|
||
4. Open a **new** terminal and verify:
|
||
```shell
|
||
mvn -version
|
||
```
|
||
It should display the Maven version and confirm it is using your JDK 8.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 3 — Configure Maven for the Private Gitea Registry
|
||
|
||
The TrizStock project has several legacy dependencies that are not available on Maven Central. They are hosted on the team's private Maven registry in Gitea. Without this configuration, your build will fail to resolve those dependencies.
|
||
|
||
1. Navigate to the Maven user settings file. If it does not exist, create it:
|
||
```URI
|
||
C:\Users\YOUR_WINDOWS_USERNAME\.m2\settings.xml
|
||
```
|
||
2. Download the `settings.xml.template` from the team [resources repository](http://145.239.66.197:3000/othmane/team-resources/src/branch/main/_global/maven/settings.xml.template).
|
||
3. Copy the template content into your `settings.xml` and replace the placeholders with your actual Gitea credentials:
|
||
```XML
|
||
<settings>
|
||
<servers>
|
||
<server>
|
||
<id>gitea</id>
|
||
<username>othmane</username>
|
||
<password>54465f0ce0fec1a357eb7d9f7055e3df873db114</password>
|
||
</server>
|
||
</servers>
|
||
</settings>
|
||
```
|
||
Verify the registry is accessible by running the following in a terminal (once you have the project cloned — see Step 7):
|
||
```shell
|
||
mvn dependency:resolve
|
||
```
|
||
All dependencies, including the legacy ones, should resolve without errors.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 4 — Install Apache Tomcat 9
|
||
|
||
1. Download **Tomcat 9** (zip distribution — do **not** use the Windows installer):
|
||
- [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/apache-tomcat-9.0.117)
|
||
- [Apache](https://tomcat.apache.org/download-90.cgi)
|
||
2. Extract it to a stable path with no spaces (e.g., `C:\dev\tomcat9`).
|
||
3. **Do not add Tomcat to your system PATH.** NetBeans will manage it directly and only needs to know the directory.
|
||
|
||
> 📝 **Note — Tomcat is not installed as a Windows service in this setup.**
|
||
>
|
||
> Using the zip distribution means Tomcat is managed entirely by NetBeans during development — it starts and stops automatically when you run or stop your project from the IDE. It does not run in the background, does not appear in `services.msc`, and does not start with Windows. This is intentional for a development environment.
|
||
>
|
||
> If you ever need to run Tomcat outside of NetBeans (e.g., for a manual deployment or testing), you can start it directly by running `C:\dev\tomcat9\bin\startup.bat` from a terminal, and stop it with `shutdown.bat`. You can also register it as a Windows service separately if needed — ask your team lead.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 5 — Install Microsoft SQL Server 2012 and SSMS
|
||
|
||
## 5.1 — Install SQL Server 2012
|
||
|
||
1. Obtain the SQL Server 2012 installer (`SQLEXPR_x64_ENU.exe`) from:
|
||
- [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/SQLEXPR_x64_ENU)
|
||
- [Microsoft](https://www.microsoft.com/en-us/download/details.aspx?id=56042)
|
||
2. Run the installer and choose **New SQL Server stand-alone installation**.
|
||
3. On the **"Database Engine Configuration"** screen, under **Authentication Mode**, select **Mixed Mode** (SQL Server Authentication and Windows Authentication).
|
||
4. Set the **SA account password** when prompted. Use the team standard password: `Root123456`.
|
||
5. Complete the installation.
|
||
|
||
## 5.2 — Enable TCP/IP and Port 1433
|
||
|
||
SQL Server disables TCP/IP by default on fresh installations. The application needs it to connect.
|
||
|
||
1. Open **SQL Server Configuration Manager** (search for it in the Start menu).
|
||
2. Expand **SQL Server Network Configuration → Protocols for MSSQLSERVER**.
|
||
3. Right-click **TCP/IP** → **Enable**.
|
||
4. Double-click **TCP/IP** → go to the **IP Addresses** tab → scroll to **IPAll** → set **TCP Port** to `1433`.
|
||
5. Click **OK**.
|
||
|
||
## 5.3 — Enable the SQL Server Browser Service
|
||
|
||
1. In **SQL Server Configuration Manager**, go to **SQL Server Services**.
|
||
2. Right-click **SQL Server Browser** → **Properties** → **Service** tab → set **Start Mode** to **Automatic**.
|
||
3. Right-click **SQL Server Browser** → **Start**.
|
||
|
||
## 5.4 — Restart the SQL Server Service
|
||
|
||
1. In **SQL Server Services**, right-click **SQL Server (MSSQLSERVER)** → **Restart**.
|
||
|
||
## 5.5 — Configure the Windows Firewall
|
||
|
||
1. Open **Windows Defender Firewall with Advanced Security** (search in Start menu).
|
||
2. Click **Inbound Rules → New Rule**.
|
||
3. Select **Port → TCP → Specific local ports: `1433`**.
|
||
4. Select **Allow the connection**.
|
||
5. Apply to all profiles (Domain, Private, Public).
|
||
6. Name the rule `SQL Server 1433` and click **Finish**.
|
||
|
||
## 5.6 — Create the Application Database Login
|
||
|
||
1. Install **SQL Server Management Studio (SSMS)**. Download from [Microsoft](https://aka.ms/ssmsfullsetup).
|
||
2. Open SSMS and connect to your local instance:
|
||
- Server name: `localhost`
|
||
- Authentication: **SQL Server Authentication**
|
||
- Login: `sa`
|
||
- Password: `Root123456`
|
||
|
||
> 📝 **Note — Check your `database.properties` before proceeding.**
|
||
>
|
||
> Open your `database.properties` file and check the value of `db.username`.
|
||
> - If it is **`sa`**, skip steps 3–9 entirely. The `sa` account already exists and was configured with the correct password (`Root123456`) during installation. No new login needs to be created.
|
||
> - If it is **any other username**, continue with steps 3–9 below to create that login.
|
||
|
||
3. In **Object Explorer**, expand **Security → Logins**.
|
||
4. Right-click **Logins → New Login**.
|
||
5. Set the login name and password to match what is in `database.properties` (provided by your team lead).
|
||
6. On the **General** page, make sure **Login** status at the bottom is set to **Enabled** (this is the default, but confirm it is not set to Disabled).
|
||
7. On the **Status** page, under **Login**, confirm it is set to **Enabled** and under **Permission to connect to database engine**, confirm it is set to **Grant**.
|
||
8. On the **Server Roles** page, check **`dbcreator`** and **`public`**.
|
||
9. Click **OK**.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 6 — Restore the Test Database
|
||
|
||
1. Download the Stock project test database backup file from the [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/life_07-04-2026).
|
||
2. Open **SSMS** and connect to your local SQL Server instance.
|
||
3. In **Object Explorer**, right-click **Databases → Restore Database…**
|
||
4. Select **Device** as the source, click **…** (Browse), then click **Add** and navigate to the downloaded `.bak` file. Click **OK**.
|
||
5. The backup details will populate in the **Backup sets to restore** grid. Confirm the correct entry is checked.
|
||
6. Click **OK** to restore. A success dialog will appear when complete.
|
||
7. In **Object Explorer**, right-click **Databases → Refresh**. The `TrizStockLife` database should now appear.
|
||
8. Verify the application login created in Step 5.6 has access:
|
||
- Expand **TrizStockLife → Security → Users**
|
||
- If your application login is not listed, right-click **Users → New User**, and map the login to this database with the **`db_owner`** role.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 7 — Install and Configure Git
|
||
|
||
## 7.1 — Install Git
|
||
|
||
1. Install **Git** if not already installed. [Download from here](https://git-scm.com/download/win).
|
||
2. Run the installer. When prompted for the default editor, choose whichever you are comfortable with (Notepad is fine for occasional use).
|
||
3. On the **"Adjusting your PATH environment"** screen, select **"Git from the command line and also from 3rd-party software"** — this makes Git available in CMD, PowerShell, and Cygwin.
|
||
4. Complete the rest of the installation with default settings.
|
||
5. Verify the installation by opening a **new** terminal and running:
|
||
```Shell
|
||
git --version
|
||
```
|
||
|
||
## 7.2 — Configure Your Identity
|
||
|
||
Git requires a name and email to be set before you can make any commit. These are embedded in every commit you create and must match your Gitea identity.
|
||
|
||
```Shell
|
||
git config --global user.name "Your Full Name"
|
||
git config --global user.email "your.email@company.com"
|
||
```
|
||
|
||
> Use the same email address as your Gitea account.
|
||
|
||
## 7.3 — Configure Line Endings
|
||
|
||
This is a **critical setting** for the team. Incorrect line ending configuration causes unnecessary diffs, pollutes commit history, and can break file parsing on the server side.
|
||
|
||
Run the following commands exactly as written:
|
||
|
||
```Shell
|
||
git config --global core.autocrlf false
|
||
git config --global core.eol lf
|
||
```
|
||
|
||
| Setting | Value | Reason |
|
||
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
|
||
| `core.autocrlf` | `false` | Disables automatic line ending conversion. Git will not touch line endings on checkout or commit. |
|
||
| `core.eol` | `lf` | Enforces LF (`\n`) as the line ending for all files in the working tree, consistent with the server and Linux environments. |
|
||
|
||
> ⚠️ **Do not skip this step.** If `autocrlf` is left at its Windows default of `true`, Git will silently convert all line endings to CRLF on checkout and back to LF on commit. This causes every file to appear modified on Windows even when no real changes were made.
|
||
|
||
## 7.4 — Configure Default Branch Name
|
||
|
||
The team uses `master` as the default branch name. Set this to avoid a mismatch when creating new local branches:
|
||
|
||
```Shell
|
||
git config --global init.defaultBranch master
|
||
```
|
||
|
||
## 7.5 — Verify Your Configuration
|
||
|
||
Run the following to confirm all settings were applied correctly:
|
||
|
||
```Shell
|
||
git config --global --list
|
||
```
|
||
|
||
You should see at minimum:
|
||
|
||
```Shell
|
||
user.name=Your Full Name
|
||
user.email=your.email@company.com
|
||
core.autocrlf=false
|
||
core.eol=lf
|
||
init.defaultbranch=master
|
||
```
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 8 — Clone the Project Repository
|
||
|
||
1. Open a terminal and clone the Stock repository:
|
||
```Shell
|
||
git clone http://145.239.66.197:3000/TrizTech/TrizStockRepository.git
|
||
```
|
||
2. When prompted, enter your Gitea username and password (or token if your Gitea instance requires it).
|
||
3. Navigate into the project folder:
|
||
```Shell
|
||
cd TrizStockRepository
|
||
```
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 9 — Configure `database.properties`
|
||
|
||
The `database.properties` file contains the local database connection settings. It is **never stored in the repository** for security reasons. You need to create it manually.
|
||
|
||
1. Download the template from the [team resources repository](http://145.239.66.197:3000/othmane/team-resources/src/branch/main/uses/stock).
|
||
2. Copy the template into the correct location inside your local repository:
|
||
```URI
|
||
\src\main\resources\database.properties
|
||
```
|
||
3. Open the file in any text editor and fill in your local values:
|
||
```properties
|
||
db.host=localhost
|
||
db.port=1433
|
||
db.name=TrizStockLife
|
||
db.username=YOUR_DB_USERNAME
|
||
db.password=YOUR_DB_PASSWORD
|
||
```
|
||
4. Verify that `database.properties` is listed in the project's `.gitignore`:
|
||
```gitignore
|
||
# In the project root, open .gitignore and confirm this line exists:
|
||
database.properties
|
||
```
|
||
If it is not there, add it. **Never commit this file.**
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 10 — Install and Configure NetBeans 17
|
||
|
||
## 10.1 — Install NetBeans
|
||
|
||
1. Download **NetBeans 17** from:
|
||
- [Gitea release assets](http://145.239.66.197:3000/othmane/team-resources/releases/tag/Apache-NetBeans-17-bin-windows-x64)
|
||
- [Apache](https://netbeans.apache.org/front/main/download/nb17/)
|
||
2. Run the installer and complete the installation with default settings.
|
||
|
||
## 10.2 — Register JDK 8
|
||
|
||
NetBeans may detect a newer JDK if you have one installed. Ensure it is using JDK 8 for this project.
|
||
|
||
1. Open NetBeans → **Tools → Java Platforms**.
|
||
2. Check that **JDK 1.8** is listed. If not, click **Add Platform**, select **Java Standard Edition**, and navigate to your JDK 8 installation directory (your `JAVA_HOME` path).
|
||
3. Click **Finish**, then **Close**.
|
||
|
||
## 10.3 — Register Tomcat 9
|
||
|
||
1. Go to **Tools → Servers → Add Server**.
|
||
2. Select **Apache Tomcat or TomEE** and click **Next**.
|
||
3. Set the **Server Location** to your Tomcat 9 directory (e.g., `C:\dev\tomcat9`).
|
||
4. Set a username and password for the Tomcat manager (you can use any values for local development, e.g., `admin` / `admin`).
|
||
5. Click **Finish**.
|
||
|
||
## 10.4 — Configure Maven in NetBeans
|
||
|
||
1. Go to **Tools → Options → Java → Maven**.
|
||
2. Under **Maven Home**, click **Browse** and point it to your Maven installation directory (`C:\dev\maven`). Do not use the **"Bundled"** option.
|
||
3. Click **OK**.
|
||
|
||
## 10.5 — Open the Project
|
||
|
||
1. Go to **File → Open Project**.
|
||
2. Navigate to your cloned `stock` folder and select it. NetBeans will recognize it as a Maven project.
|
||
3. Click **Open Project**.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Step 11 — Build and Verify
|
||
|
||
This final step confirms that your entire environment is wired up correctly.
|
||
|
||
## 11.1 — Build the Project
|
||
|
||
1. In NetBeans, right-click the **Stock** project in the Projects panel.
|
||
2. Select **Clean and Build**.
|
||
3. Monitor the **Output** panel at the bottom. The build must end with:
|
||
```Log
|
||
BUILD SUCCESS
|
||
```
|
||
If you see `BUILD FAILURE` with dependency errors, revisit Step 3 (Maven settings.xml and Gitea registry).
|
||
|
||
## 11.2 — Deploy and Run
|
||
|
||
1. Right-click the project → **Run**.
|
||
2. NetBeans will deploy the application to your local Tomcat 9 instance and open it in the browser.
|
||
3. The application should load without any database connection errors.
|
||
|
||
## 11.3 — Verify Database Connectivity
|
||
|
||
1. Log in to the application using the test credentials (ask your team lead for the default test user).
|
||
2. Navigate to any section that loads data from the database (e.g., the stock listing page).
|
||
3. If data loads correctly, your environment is fully operational.
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Troubleshooting
|
||
|
||
| **Symptom** | **Likely Cause** | **Fix** |
|
||
| ------------------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||
| `java -version` shows wrong version or not found | `JAVA_HOME` or `PATH` not set correctly | Revisit Step 1, open a **new** terminal after changes |
|
||
| `javac` not found | JRE installed instead of JDK | Reinstall using the JDK download |
|
||
| `mvn -version` not found | `mvn -version` not found | Revisit Step 2 |
|
||
| Maven build fails with dependency not found | `settings.xml` not configured or wrong credentials | Revisit Step 3 |
|
||
| Cannot connect to SQL Server from SSMS | TCP/IP disabled or port 1433 blocked | Revisit Steps 5.2 and 5.5 |
|
||
| Application fails to connect to DB at runtime | Wrong credentials in `database.properties`, or TCP/IP not enabled | Revisit Steps 5.2 and 9 |
|
||
| `database.properties` not found at runtime | File placed in wrong directory | Confirm the file is at `\src\main\resources\database.properties` |
|
||
| Tomcat not found in NetBeans | Server not registered | Revisit Step 10.3 |
|
||
| NetBeans using wrong JDK | JDK 8 not registered as a Java Platform | Revisit Step 10.2 |
|
||
| Build succeeds but app doesn't start | Tomcat configuration issue | Check the NetBeans Output panel for the full stack trace |
|
||
|
||
<div style={{pageBreakBefore: 'always'}}></div>
|
||
|
||
# Reference Links
|
||
|
||
| **Resource** | **URL** |
|
||
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
||
| Team Resources Repository | [LINK](http://145.239.66.197:3000/othmane/team-resources) |
|
||
| Stock Project Repository | [LINK](http://145.239.66.197:3000/TrizTech/TrizStockRepository) |
|
||
| Stock Database Release Assets | [LINK](http://145.239.66.197:3000/othmane/team-resources/releases/tag/life_07-04-2026) |
|
||
| Gitea Maven Registry | [LINK](http://145.239.66.197:3000/othmane/-/packages/) |
|
||
| `database.properties` Template | [LINK](http://145.239.66.197:3000/othmane/team-resources/src/branch/main/uses/stock/database.properties) |
|
||
| `settings.xml` Template | [LINK](http://145.239.66.197:3000/othmane/team-resources/src/branch/main/_global/maven/settings.xml.template) |
|