ALP-CONNEX Interactive Installer
The ALP-CONNEX project ships with an interactive Bash installer that generates all configuration files required for a Docker Compose deployment. The script is located at:
examples/install.sh
Prerequisites
| Requirement | Minimum Version |
|---|---|
| Linux (Bash 4+) | Ubuntu 20.04 / Debian 11 / RHEL 8 |
| Docker Engine | 24.0+ |
| Docker Compose | V2 (plugin) |
The installer checks for Docker and Compose V2 automatically and will abort with an error if either is missing.
Quick Start
# Download or copy the script to your server
chmod +x install.sh
# Run the installer
./install.sh
Installation Modes
The installer offers three modes on startup:
| Mode | Description |
|---|---|
| 1) Full stack | Deploy the complete ALP-CONNEX platform from scratch |
| 2) Add connector | Add an IEC 104 or MQTT connector to an existing stack |
| 3) Edit UUIDs | Update connector configuration IDs in an existing deployment |
Mode 1 — Full Stack Deployment
This mode walks through all configuration steps and generates the deployment files.
Configuration Steps
1. Installation Directory
The target directory where all generated files will be placed.
- Default:
./alp-connex
2. Host Configuration
The IP address of the host machine. This is used by the browser to reach the API and is auto-detected when possible.
3. Database Configuration
| Parameter | Default | Description |
|---|---|---|
| PostgreSQL user | postgres | Database username |
| PostgreSQL password | (required) | Database password |
| PostgreSQL database | alpconnex | Database name |
Important: PostgreSQL only reads
POSTGRES_PASSWORDduring initial database creation. If you re-install with a different password, you must first remove the existing volume:docker volume rm <project>_db-data
4. Image Versions
Enter the image tags provided to you for each component:
TAG_MANAGEMENT— Management UI + APITAG_IEC104— IEC 104 ConnectorTAG_MQTT— MQTT Connector
5. Connector Configuration IDs
UUIDs generated by the Management UI when creating a connector. You can use placeholder UUIDs (00000000-0000-0000-0000-000000000000) during initial setup and update them later via Mode 3 or by editing the .env file.
6. Service Ports
Configure the host port for each service. Internal container ports remain fixed.
| Service | Default Host Port | Internal Port |
|---|---|---|
| Frontend (Management UI) | 4200 | 8080 |
| Backend (Management API) | 8080 | 8080 |
| PostgreSQL | 5432 | 5432 |
| Valkey (Redis) | 6379 | 6379 |
| IEC 104 Connector | 2404 | 2404 |
| Mosquitto (if included) | 1883 | 1883 |
7. MQTT Broker
Choose between:
- Local Mosquitto — Deploys Eclipse Mosquitto 2 as part of the stack
- External broker — Connects to a broker on another machine (you provide hostname/IP and port)
8. Demo / Seed Data
Optionally enable SEED_DATA=true in the backend to have it ingest demo connectors, mappings, and signals on startup.
9. OAuth / Microsoft Entra ID (optional)
Enable OAuth authentication by providing three values from your Azure App Registrations:
| Input | Description |
|---|---|
| Tenant ID | Azure AD Directory (tenant) ID |
| API Client ID | Backend app registration client ID |
| SPA Client ID | Frontend app registration client ID |
All other OAuth values (audience, scopes, authority, redirect URI) are derived automatically.
See deployment_oAuth.md for detailed Entra ID setup instructions.
Generated Files
| File | Description |
|---|---|
.env | All configuration variables |
docker-compose.yaml | Complete Docker Compose stack definition |
mosquitto/config/mosquitto.conf | Mosquitto configuration (only if local broker is selected) |
Post-Generation
After generating the files, the installer offers to:
- Login to the container registry (
registry.alpscale.io) - Start the stack with
docker compose up -dand follow logs
Mode 2 — Add Connector
Add an additional IEC 104 or MQTT connector to an existing deployment without regenerating the entire stack.
Workflow
- Provide the path to the existing installation (must contain
docker-compose.yaml) - Select the connector type (IEC 104 or MQTT)
- Configure the new connector:
IEC 104:
| Parameter | Default |
|---|---|
| Service name | iec104-server-2 |
| Image tag | (required) |
| Connector ID (UUID) | (required) |
| Host port | 2404 |
MQTT:
| Parameter | Default |
|---|---|
| Service name | mqtt-client-2 |
| Image tag | (required) |
| Connector ID (UUID) | (required) |
| Broker hostname | mosquitto |
| Broker port | 1883 |
- The new service block is injected into the existing
docker-compose.yaml - Optionally restart the stack to apply changes
Note: If an MQTT connector uses
mosquittoas its broker and a Mosquitto service exists in the compose file, adepends_onrelationship is automatically added.
Mode 3 — Edit Connector UUIDs
Update the configuration IDs of existing connectors without modifying any other settings.
Workflow
- Provide the path to the existing installation
- The script scans
docker-compose.yamlfor all services using--id - All discovered connectors are listed with their current UUIDs
- Enter new UUIDs for each connector (press Enter to keep the current value)
- Changes are applied to the
.envfile (for variable references) or directly indocker-compose.yaml(for hardcoded UUIDs) - Optionally restart the stack
Example Output
── Discovered Connectors ──
1) iec104-server
Current UUID: 00000000-0000-0000-0000-000000000000
2) mqtt-client
Current UUID: 00000000-0000-0000-0000-000000000000
── Enter new UUIDs ──
[INFO] Enter the UUID for each connector. Press Enter to keep the current value.
1) iec104-server [00000000-0000-0000-0000-000000000000]: a1b2c3d4-...
2) mqtt-client [00000000-0000-0000-0000-000000000000]: e5f6a7b8-...
Generated .env Reference
| Variable | Example | Description |
|---|---|---|
HOST_IP | 192.168.1.100 | Host IP for browser access |
POSTGRES_USER | postgres | Database user |
POSTGRES_PASSWORD | secret | Database password |
POSTGRES_DB | alpconnex | Database name |
TAG_MANAGEMENT | 1.0.0 | Management image tag |
TAG_IEC104 | 0.3.0 | IEC 104 connector image tag |
TAG_MQTT | 0.1.0 | MQTT connector image tag |
IEC104_CONFIG_ID | uuid | IEC 104 connector UUID |
MQTT_CONFIG_ID | uuid | MQTT connector UUID |
FRONTEND_PORT | 4200 | Frontend host port |
API_PORT | 8080 | Backend API host port |
POSTGRES_PORT | 5432 | PostgreSQL host port |
VALKEY_PORT | 6379 | Valkey host port |
IEC104_PORT | 2404 | IEC 104 host port |
MQTT_BROKER_HOST | mosquitto | MQTT broker hostname |
MQTT_BROKER_PORT | 1883 | MQTT broker port |
MOSQUITTO_PORT | 1883 | Mosquitto host port (local only) |
SEED_DATA | true | Enable demo data seeding |
OAuth variables (when enabled): AZURE_TENANT_ID, AZURE_API_CLIENT_ID, AZURE_SPA_CLIENT_ID, AZUREAD_INSTANCE, AZUREAD_AUDIENCE, AZUREAD_SCOPES, SCALAR_REDIRECT_URI, MSAL_AUTHORITY, MSAL_SCOPE
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
password authentication failed for user "postgres" | The db-data volume was initialized with a different password | Run docker compose down -v to remove volumes, then docker compose up -d |
docker-compose.yaml not found (Mode 2/3) | Wrong installation path | Provide the correct path containing docker-compose.yaml |
Docker Compose V2 is not available | Docker Compose plugin not installed | Install with sudo apt install docker-compose-plugin or update Docker |
| Port already in use | Another service occupies the port | Choose a different host port during configuration |
| Cannot pull images | Not logged into registry | Run docker login registry.alpscale.io |