TrizTech/triz-docs
15
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
05924d8649
triz-docs/docs/getting-started/environment-setup.md
Othmane Ataallah 05924d8649 v0.1
2026-04-27 11:04:04 +01:00

20 KiB
Raw Blame History

sidebar_position title description
1 Environment Setup Guide (TrizStock) Complete guide to setting up the TrizStock development environment from scratch.

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.
  • 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

Step 1 — Install Java SE Development Kit (JDK) 8

  1. Download JDK 8 from:
  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:
java -version
javac -version

Both must return 1.8.x. If javac is not found, JAVA_HOME or PATH was not set correctly.

Step 2 — Install Apache Maven

  1. Download Maven from: (Download the binary zip archive)
  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:
mvn -version

It should display the Maven version and confirm it is using your JDK 8.

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:
C:\Users\YOUR_WINDOWS_USERNAME\.m2\settings.xml
  1. Download the settings.xml.template from the team resources repository.
  2. Copy the template content into your settings.xml and replace the placeholders with your actual Gitea credentials:
<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):

mvn dependency:resolve

All dependencies, including the legacy ones, should resolve without errors.

Step 4 — Install Apache Tomcat 9

  1. Download Tomcat 9 (zip distribution — do not use the Windows installer):
  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.

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:
  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.
  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.
  1. In Object Explorer, expand Security → Logins.
  2. Right-click Logins → New Login.
  3. Set the login name and password to match what is in database.properties (provided by your team lead).
  4. 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).
  5. 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.
  6. On the Server Roles page, check dbcreator and public.
  7. Click OK.

Step 6 — Restore the Test Database

  1. Download the Stock project test database backup file from the Gitea release assets.
  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.

Step 7 — Install and Configure Git

7.1 — Install Git

  1. Install Git if not already installed. Download from here.
  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:
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.

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:

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:

git config --global init.defaultBranch master

7.5 — Verify Your Configuration

Run the following to confirm all settings were applied correctly:

git config --global --list

You should see at minimum:

user.name=Your Full Name
user.email=your.email@company.com
core.autocrlf=false
core.eol=lf
init.defaultbranch=master

Step 8 — Clone the Project Repository

  1. Open a terminal and clone the Stock repository:
git clone http://145.239.66.197:3000/TrizTech/TrizStockRepository.git
  1. When prompted, enter your Gitea username and password (or token if your Gitea instance requires it).
  2. Navigate into the project folder:
cd TrizStockRepository

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.
  2. Copy the template into the correct location inside your local repository:
\src\main\resources\database.properties
  1. Open the file in any text editor and fill in your local values:
db.host=localhost
db.port=1433
db.name=TrizStockLife
db.username=YOUR_DB_USERNAME
db.password=YOUR_DB_PASSWORD
  1. Verify that database.properties is listed in the project's .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.

Step 10 — Install and Configure NetBeans 17

10.1 — Install NetBeans

  1. Download NetBeans 17 from:
  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.

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:
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.

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

Reference Links

Resource URL
Team Resources Repository LINK
Stock Project Repository LINK
Stock Database Release Assets LINK
Gitea Maven Registry LINK
database.properties Template LINK
settings.xml Template LINK