Provision Portal Deployment (API + UI)

1. Overview

This deployment runs both Provision Portal services on a single host using Docker Compose:

  • Provision API (Spring Boot) — backend REST/SOAP API

  • Provision Portal UI (Angular on Nginx) — web interface

2. Architecture

provision-portal-diagram

3. Prerequisites

3.1. Required External Components

The following components must be installed and accessible before deployment:

Component Purpose Default Port

MySQL or Oracle

Application database + Flowable workflow engine

3306 (MySQL) / 1521 (Oracle)

Northbound API

NBI integration for TR-069 operations

8080

3.2. System Requirements

  • Docker Engine 20.10+

  • Docker Compose 2.0+

  • Minimum 2GB RAM

  • 10GB free disk space

4. Deployment Steps

4.1. 1. Prepare Environment File

The docker/ directory contains pre-configured environment templates. Choose the appropriate file based on your database:

MySQL
cd docker
cp .env.mysql .env
Oracle
cd docker
cp .env.oracle .env

4.2. 2. Configure Host Variables

Edit .env and replace placeholder values with actual hostnames or IP addresses:

# Required replacements:
~MYSQL_HOST~       → MySQL server (e.g., 192.168.1.80)
~ORACLE_HOST~      → Oracle server (for Oracle deployment)
~NORTHBOUND_HOST~  → Northbound API server (e.g., 192.168.1.60)

Example:

DB_HOST=192.168.1.80
MYSQL_HOST=192.168.1.80
FLOWABLE_MYSQL_HOST=192.168.1.80
NORTHBOUND_API_URL=http://192.168.1.60:8080/iot-webservice

4.3. 3. Deploy Services

cd docker
docker compose up -d

4.4. 4. Verify Deployment

Check service health:

docker compose ps

All services should show status as healthy or running.

5. Environment Variables

5.1. Common Variables

Variable Description Default Required

DATA_FOLDER

Base directory for persistent data and configurations

/usr/local

Yes

TZ

Timezone for all services

Europe/Kyiv

Yes

SPRING_PROFILES_ACTIVE

Spring Boot profile: mysql or oracle

mysql

Yes

DB_TIMEZONE

Database server timezone (used in MySQL JDBC URL serverTimezone parameter)

Europe/Kyiv

No

5.2. Database Configuration

MySQL
Variable Description Default

MYSQL_HOST

MySQL server address

-

MYSQL_PORT

MySQL port

3306

MYSQL_SCHEMA

Schema name

ftacs

MYSQL_USER

MySQL username

ftacs

MYSQL_PASSWORD

MySQL password

ftacs
Oracle
Variable Description Default

ORACLE_HOST

Oracle server address

-

ORACLE_PORT

Oracle port

1521

ORACLE_SERVICE

Oracle service name

XEPDB1

ORACLE_USER

Oracle username

ftacs

ORACLE_PASSWORD

Oracle password

ftacs

5.3. Flowable Database Configuration

MySQL
Variable Description Default

FLOWABLE_MYSQL_HOST

Flowable MySQL host

Same as MYSQL_HOST

FLOWABLE_MYSQL_PORT

Flowable MySQL port

3306

FLOWABLE_MYSQL_SCHEMA

Flowable schema name

flowable

FLOWABLE_MYSQL_USER

Flowable MySQL username

flowable

FLOWABLE_MYSQL_PASSWORD

Flowable MySQL password

flowable
Oracle
Variable Description Default

FLOWABLE_ORACLE_HOST

Flowable Oracle host

Same as ORACLE_HOST

FLOWABLE_ORACLE_PORT

Flowable Oracle port

1521

FLOWABLE_ORACLE_SERVICE

Flowable Oracle service

XEPDB1

FLOWABLE_ORACLE_USER

Flowable Oracle username

flowable

FLOWABLE_ORACLE_PASSWORD

Flowable Oracle password

flowable

5.4. External Dependencies

Variable Description Default Required

NORTHBOUND_API_URL

Northbound API base URL

http://NORTHBOUND_HOST:8080/iot-webservice

Yes

TIMEOUT

Provisioning operation timeout in seconds

60

No

TRANSACTION_DELAY

Extra delay (ms) after transaction response before accepting the result. Allows ACS to finalize task statuses (e.g. late FailedCount). Default is 1000 ms; increase this value under heavy ACS load

1000

No

5.5. Provision API Internal Configuration

Variable Description Default Required

XML_PATH

Path to XML configuration files inside the container

file:/etc/app/xml/

Yes

CONFIG_PATH

Path to additional configuration files inside the container

file:/etc/app/config/

Yes
These paths must match the directory structure inside the mounted volume (provision-api-conf). See Data Persistence for volume layout.

5.6. Logging

Variable Description Default Required

LOGGING_LEVEL_COM_FRIENDLY_PROVISIONPORTAL

Log level for the application package (com.friendly.provisionportal). Values: ERROR, WARN, INFO, DEBUG. In DEBUG mode business errors include stack traces. Can also be changed at runtime via Actuator.

DEBUG

No

5.7. Service Port Configuration

Variable Description Default Required

FT_PROV_API_HTTP_PORT

Provision API HTTP port on host

8085

Yes

FT_PROV_API_JAVA_RAM

JVM memory settings for Provision API

-XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=70

No

FT_PROV_PORTAL_HTTP_PORT

Provision Portal UI HTTP port on host

8890

Yes

FT_PROV_PORTAL_HTTPS_PORT

Provision Portal UI HTTPS port on host

8893

No

6. Service Access

After successful deployment, access services at:

Service URL Description

Provision Portal UI

http://<HOST>:8890/provision-portal/

Web interface

Provision API (SOAP)

http://<HOST>:8085/prov-portal/soap/ProvWS?wsdl

SOAP API WSDL

Provision API (Health)

http://<HOST>:8085/prov-portal/actuator/health

Health check endpoint

7. Exposed Ports

Port Service Protocol Configurable Via

8890

Provision Portal UI (Nginx)

HTTP

FT_PROV_PORTAL_HTTP_PORT

8893

Provision Portal UI (Nginx)

HTTPS

FT_PROV_PORTAL_HTTPS_PORT

8085

Provision API (Spring Boot)

HTTP

FT_PROV_API_HTTP_PORT
Debug port 5005 is not exposed by default. See Remote Debugging for details.

To verify ports are listening:

netstat -tlnp | grep -E '8890|8893|8085'
# or
ss -tlnp | grep -E '8890|8893|8085'

8. Service Startup Order

Services start in the following order with health checks:

  1. Provision API — REST/SOAP backend (waits for database availability)

  2. Provision Portal UI — Web interface (waits for Provision API to become healthy)

9. Data Persistence

Persistent data is stored in the following locations (assuming DATA_FOLDER=/usr/local):

Service Path Content

Provision API Config

${DATA_FOLDER}/provision-api-conf

Spring Boot configs, XML configs (must be pre-configured)

Provision API Logs

${DATA_FOLDER}/provision-api/logs

Application logs

SSL Certificates

${DATA_FOLDER}/provision-portal/ssl

SSL certificates for Nginx

Portal Nginx Logs

${DATA_FOLDER}/provision-portal/nginx/logs

Nginx access and error logs

10. Remote Debugging

By default, JDWP remote debugging is disabled to prevent unnecessary CPU usage and security risks from external port scanning.

To enable debugging, use compose.debug.yml as an override:

cd docker
docker compose -f compose.yml -f compose.debug.yml up -d

This exposes JDWP on 127.0.0.1:5005 (localhost only) and adds the debug agent to JVM options.

Variable Description Default

FT_PROV_API_DEBUG_PORT

Debug port on host (localhost only)

5005
Never expose port 5005 to the public network. External scanners will continuously hit the JDWP port, causing high CPU usage and potential security vulnerabilities.

11. Troubleshooting

11.1. Check Service Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f provision-api
docker compose logs -f provision-portal

11.2. Common Issues

11.2.1. Services Not Starting

Check if all external dependencies are accessible:

# Test database connection
telnet <DB_HOST> 3306    # MySQL
telnet <DB_HOST> 1521    # Oracle

# Test Northbound API
curl http://<NORTHBOUND_HOST>:8080/iot-webservice

11.2.2. Health Check Failing

Wait for services to fully initialize. Health checks run every 10 seconds:

docker compose ps

If a service remains unhealthy after 5 minutes, check its logs.

11.2.3. Port Already in Use

If ports are already in use, modify port mappings in .env:

FT_PROV_API_HTTP_PORT=8085
FT_PROV_PORTAL_HTTP_PORT=8890
FT_PROV_PORTAL_HTTPS_PORT=8893

11.3. Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart provision-api

12. Maintenance

12.1. Update Services

Pull latest images and restart:

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

12.2. Force Repull Images

Force Docker to pull fresh images (ignores cache):

# Stop services
docker compose down

# Remove existing images
docker images | grep "hub.friendly-tech.com" | grep "provision" | awk '{print $3}' | xargs docker rmi -f

# Start with fresh images
docker compose up -d

12.3. Stop Services

# Stop services (keeps data)
docker compose down

12.4. View Resource Usage

docker stats