SeaTech

🌊 About the Project

SeaTech is part of the broader INCONE60 Green – Digital and Green Transition of Small Ports initiative (2024–2026), a pioneering European project aimed at accelerating the digital and sustainable transformation of small and medium ports.

Project Overview

The INCONE60 Green project focuses on making small ports smarter, greener, and more efficient. Through the use of innovative technologies such as AI-driven analytics, digital twins, and automation, the project supports environmentally friendly logistics and port management practices that reduce emissions and optimize operations.
By connecting stakeholders — from port management and shipping agencies to vessel operators — INCONE60 Green fosters collaboration, knowledge exchange, and economic growth across the South Baltic region.

Vision and Mission

Our mission is to enable small ports to operate efficiently while minimizing environmental impact. The project promotes:

• Smarter digital workflows and real-time data management,
• Green logistics solutions that reduce the carbon footprint,
• Cross-border collaboration and innovation for sustainable maritime development.

Funding

This initiative is realized within the framework of the Interreg South Baltic Programme 2021–2027,
Co-financed by the European Regional Development Fund: 1 548 720 EUR
Project ID: STHB.01.01.-IP.01-0009/23
Title: INCONE60 – Digital and Green Transition of Small Ports

SeaTech Module

SeaTech serves as one of the core digital tools developed within INCONE60 Green — a web-based platform supporting small port operations, vessel traffic visualization, and cost management automation using data sources such as AIS (VesselFinder).
The system is based on Java Spring, Angular, Docker, and Keycloak for IAM integration, enabling both port authorities and agents to collaborate securely and efficiently.

---

🧭 Summary of this README

This README provides a complete guide for developers and technical teams working on the SeaTech module, including:

• Environment setup and prerequisites,
• Configuration for port-specific data,
• Instructions for running Dockerized environments,
• Keycloak authentication setup,
• E2E testing and project structure.

📋 Table of Contents

• Prerequisites
• Quick Start
• Port-Specific Configuration
• Development Setup
  • Initial Configuration
  • Running Dependencies
  • Running the Full Application
  • Local Frontend Development
• Closed-Source Dependencies
• Keycloak Configuration
• Testing
  • Running E2E Tests
  • Developing E2E Tests
• Project Structure

---

Prerequisites

• Docker and Docker Compose (for containerized deployment)
• Java 21+ (for backend development)
• Node.js 18+ and npm (for frontend development)
• Maven 3.8+ (or use the included Maven Wrapper)

Quick Start

1. Configure hosts file (see Initial Configuration)
2. Set up port-specific data (see Port-Specific Configuration)
3. Start dependencies: docker-compose --profile deps up --build
4. Start application: docker-compose --profile app up --build
5. Access the application: http://localhost:4200

Port-Specific Configuration

⚠️ Before running the application, you must configure your port-specific data.

For detailed instructions on preparing port-specific data including:

• Quay definitions (berths, bollards, depths)
• Cost types and pricing (commodity dues, services, shipping dues)
• Port map and quay annotations
• Port logo and branding

👉 See the complete guide in seatech-backend/README.md

This configuration is essential for the system to work correctly with your port's infrastructure and pricing.

---

Development Setup

Initial Configuration

Add the following entry to your hosts file:

Linux/Mac: /etc/hosts Windows: C:\Windows\System32\drivers\etc\hosts

127.0.0.1 keycloak.seatech

This allows the application to properly resolve the Keycloak authentication server.

Running Dependencies

Start the required infrastructure services (databases, Keycloak, and mail server):

docker-compose --profile deps up --build

This command starts:

• PostgreSQL - Database for Keycloak
• PostgreSQL - Database for the backend application
• Keycloak - Authentication and authorization server
  • Admin console: http://localhost:8080/
  • Login credentials:
    • Username: admin
    • Password: admin
  • Test user account:
    • Username: user1
    • Password: password1
  • On first run, imports realm configuration from keycloak/import/seatech-realm.json
• MailHog - Local SMTP server for testing email notifications
  • SMTP port: 1025
  • Web interface: http://localhost:8025

Running the Full Application

1. Create Environment File

Create a .env file in the root directory with the following variables:

ANGULAR_BUILD_CONFIGURATION=<angular_build_configuration>

• ANGULAR_BUILD_CONFIGURATION: Optional, defaults to local-neverland-port

The closed-source artifacts required by the build are described in Closed-Source Dependencies.

2. Start the Application

docker-compose --profile app up --build

This starts both the backend and frontend services. The application will be available at:

• Frontend: http://localhost:4200
• Backend API: http://localhost:9090

Local Frontend Development

For faster frontend development without Docker:

npm run start-${portName}

Examples:

# For "neverland-port" port
npm run start-neverland-port


This allows hot-reloading during development while connecting to the backend running in Docker.

---

## Closed-Source Dependencies

### Backend `commons` libraries

The backend depends on three closed-source `commons` libraries (`commons-email`,
`commons-excel`, `commons-auth`, version `3.0.0`). They are **vendored** in the
in-project Maven repository at `seatech-backend/local-maven-repo` (committed to the
repository) and resolved via `file://`, so **no external Maven access and no extra
setup are required** to build.

To update them, drop the new `jar` + `pom` into the matching
`local-maven-repo/commons/<artifact>/<version>/` directory (standard Maven repository
layout) and bump `commons-version` in `seatech-backend/pom.xml`.

### Keycloak provider

seatech-backend calls the custom endpoint `/realms/{realm}/ext/users`, provided by
the closed-source `users-management-ext` Keycloak SPI. Its jar is **vendored** in
`keycloak/providers/` (committed to the repository) and baked into the Keycloak image
by `kc.sh build`, so no extra setup is required.

To update it, replace the jar in `keycloak/providers/` and rebuild the Keycloak
image.

---

## Keycloak Configuration

### Exporting Realm Configuration

If you need to export the current Keycloak realm configuration:

1. **Stop the dependencies** (if running)

2. **Run the export profile:**

   ```cmd
   docker-compose --profile realm-export up

3. Wait for completion. Keycloak will display:

   INFO  [org.keycloak.services] (main) KC-SERVICES0034: Export of realm 'seatech' requested.
   INFO  [org.keycloak.exportimport.singlefile.SingleFileExportProvider] (main) Exporting realm 'seatech' into file /tmp/realm-export/seatech-realm.json
   INFO  [org.keycloak.services] (main) KC-SERVICES0035: Export finished successfully
   ...
   INFO  [io.quarkus] (main) Keycloak stopped in 0.075s
   

4. Stop the container with Ctrl+C

5. Find the export at keycloak/import/seatech-realm.json

---

Testing

Running E2E Tests

⚠️ Warning: E2E tests will delete all NoAs before running!

Prerequisites:

1. Start dependencies with docker-compose --profile deps up
2. Start the backend and frontend

Run tests:

cd seatech-frontend
npm install
npx cypress run --browser chrome

Developing E2E Tests

1. Start all services (dependencies, backend, frontend)

2. Open Cypress GUI:

   cd seatech-frontend
   npx cypress open

3. Select "E2E Testing"

4. Choose a browser

5. Select and run specs

Test Locations:

• Test files: ./seatech-frontend/cypress/e2e/
• Common code: ./seatech-frontend/cypress/support/

---

Additional Resources

• Backend Configuration: See seatech-backend/README.md for detailed backend setup and port data configuration
• Frontend Development: Check seatech-frontend/ for Angular-specific documentation

---

Support

For issues, questions, or contributions, please contact the development team or open an issue in the project repository.