CLI (infra.sh)

Main Script: `infra.sh`

The infra.sh script is the main entrypoint to manage infrastructure (local + remote). Per-service run.sh files may exist as thin wrappers, but this guide assumes infra.sh.

General Syntax

./infra.sh [command] [project|path|service] [options]

Main Commands

`up` - Start Services

Start the full stack

./infra.sh up

This starts, in order:

core project (Mosquitto, Telegraf, InfluxDB, Grafana)
kafka project (Kafka, Zookeeper, Kafka UI)
thingsboard project (ThingsBoard + PostgreSQL)
microservices project (Data Aggregator)
airflow project (Airflow stack)

Start a specific project

./infra.sh up kafka              # Only Kafka cluster
./infra.sh up thingsboard        # Only ThingsBoard
./infra.sh up microservices      # Only microservices
./infra.sh up airflow            # Only Airflow
./infra.sh up core               # Only base services

Start by folder paths

./infra.sh up infrastructure/mosquitto        # Only Mosquitto
./infra.sh up data-layer/influxdb             # Only InfluxDB
./infra.sh up ingestion/telegraf              # Only Telegraf
./infra.sh up platform/thingsboard            # Full ThingsBoard
./infra.sh up visualization/grafana           # Only Grafana

`down` - Stop and Remove Containers

Stop everything

./infra.sh down

Stop a specific project

./infra.sh down kafka
./infra.sh down thingsboard
./infra.sh down microservices

Stop by paths

./infra.sh down infrastructure/mosquitto
./infra.sh down ingestion/telegraf

Note: down stops and removes containers, but it does NOT delete data volumes.

`clean` - Cleanup Containers and Data

Clean containers (preserve data)

./infra.sh clean

Clean EVERYTHING including data (DESTRUCTIVE)

./infra.sh clean --data

Clean a specific project

./infra.sh clean kafka
./infra.sh clean thingsboard --data

`restart` - Restart Services

Restart the full stack

./infra.sh restart

Restart a specific project

./infra.sh restart thingsboard
./infra.sh restart kafka

Restart by paths

./infra.sh restart platform/thingsboard
./infra.sh restart infrastructure/mosquitto

`status` - Show Status

Status of all projects

./infra.sh status

Shows status for:

core project
kafka project
thingsboard project
microservices project
airflow project

Status of a specific project

./infra.sh status kafka
./infra.sh status thingsboard

Status by paths

./infra.sh status infrastructure/kafka

`logs` - View Logs

View core project logs

./infra.sh logs core

View logs for a specific project

./infra.sh logs kafka
./infra.sh logs thingsboard
./infra.sh logs airflow

View logs for a specific service

./infra.sh logs core telegraf          # Telegraf logs
./infra.sh logs kafka broker           # Kafka broker logs
./infra.sh logs thingsboard thingsboard # ThingsBoard logs

View logs by paths

./infra.sh logs ingestion/telegraf
./infra.sh logs infrastructure/mosquitto
./infra.sh logs data-layer/influxdb

`build` - Rebuild Images

Rebuild all images

./infra.sh build

Warning: This can take several minutes and rebuilds ALL images without cache.

Rebuild a specific project

./infra.sh build thingsboard
./infra.sh build microservices

Rebuild by paths

./infra.sh build platform/thingsboard
./infra.sh build ingestion/telegraf

`install` - Initial Installation

Some projects require an initial install step (e.g. database initialization).

./infra.sh install thingsboard

`build-tb` - Build Customized ThingsBoard

Special case: ThingsBoard requires building from source to apply UI customizations.

Build normal

./infra.sh build-tb

Process:

Clone the official ThingsBoard repository
Apply customizations from platform/thingsboard/custom/src/
Build backend (Maven)
Build frontend (Angular)
Copy JARs to platform/thingsboard/bin/

Estimated time: 15-30 minutes (first time)

See thingsboard.md for the service-specific build and runtime notes.

`generate-env` - Environment Generation

./infra.sh env generate

Generates deployment/topology.env, .env, .env.secrets, and per-project */.env files from templates.

Typical usage:

./infra.sh env generate
./infra.sh env check

`generate-configs` - Generate Config Files

bash ./deployment/scripts/config-generators/generate-configs.sh

Generates config files from templates (.template files) using variables from .env.

`fix-permissions` - Fix Permissions

bash ./deployment/scripts/utils/fix_permissions.sh

Fixes file/directory permissions that can cause Docker issues.

`test` - Run Tests

The test command validates different aspects of the infrastructure:

Ansible config test (fast, non-destructive)

./infra.sh test health

Time: ~seconds

Docker infrastructure test (destructive)

./infra.sh test infra

Does:

Full cleanup with clean --data
Starts services with up
Validates connectivity and health checks
Scans logs for errors

Warning: This test is DESTRUCTIVE and will delete all data.

Available Projects

Use ./infra.sh list to see available projects and aliases.

Common Usage Examples

Daily development

# Full stack start
./infra.sh up

# Show overall status
./infra.sh status

# Telegraf logs (debugging)
./infra.sh logs ingestion/telegraf

# Restart only ThingsBoard after changes
./infra.sh restart platform/thingsboard

# Kafka logs for stream debugging
./infra.sh logs kafka broker

ThingsBoard frontend development

# 1. Edit files under platform/thingsboard/custom/src/

# 2. Build ThingsBoard with your changes
./infra.sh build-tb

# 3. Restart ThingsBoard to apply changes
./infra.sh restart thingsboard

# 4. Check logs to verify
./infra.sh logs thingsboard

Debugging problems

# Status of all services
./infra.sh status all

# Logs for a problematic service/project
./infra.sh logs <project>

# Restart a specific project
./infra.sh restart <project>

# If it persists, do a full rebuild
./infra.sh down
./infra.sh build <project>
./infra.sh up <project>

Testing and validation

# Quick test (non-destructive)
./infra.sh test health

# Full infrastructure test (DESTRUCTIVE)
./infra.sh test infra

Maintenance

# Airflow logs to verify DAGs
./infra.sh logs airflow airflow-scheduler

# Stop and start a project
./infra.sh down kafka
./infra.sh up kafka

# Full cleanup (CAUTION: deletes data)
./infra.sh clean --data
./infra.sh up

Access URLs

After ./infra.sh up, services are available at:

Service	URL	Default credentials
Grafana	http://localhost:3000	admin / (see `.env`)
InfluxDB	http://localhost:8086	admin / (see `.env`)
ThingsBoard	http://localhost:8080	tenant@thingsboard.org / (see `.env`)
Airflow	http://localhost:8080	airflow / airflow
Kafka UI	http://localhost:8089	(no auth)

Port conflict: ThingsBoard and Airflow both default to port 8080. Change one in .env.

Important Environment Variables

Edit .env to change:

Ports

GRAFANA_PORT=3000
INFLUXDB_PORT=8086
THINGSBOARD_PORT=8080
AIRFLOW_PORT=8082
KAFKA_BROKER_PORT=9093
MOSQUITTO_PORT_UNENCRYPTED=1883

Credentials (CHANGE IN PRODUCTION)

INFLUX_ADMIN_USER=admin
INFLUX_ADMIN_PASS=change_me
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASS=change_me
MOSQUITTO_USER=mqttuser
MOSQUITTO_PASS=change_me

Image versions

THINGSBOARD_VERSION=latest
KAFKA_VERSION=7.5.0
TELEGRAF_VERSION=1.30
INFLUXDB_VERSION=2.7
GRAFANA_VERSION=10.2.0

Direct Docker Commands

If you need more fine-grained control, you can use Docker Compose directly:

# Tail logs in real time
docker compose logs -f <service>

# Exec into a container
docker exec -it <container_name> bash

# Resource usage
docker stats

# Inspect network
source .env
docker network inspect "${DOCKER_NETWORK_NAME}"

# Volumes
docker volume ls

Troubleshooting

Service does not start

# Show detailed logs
./infra.sh logs <project>

# Verify the network exists
source .env
docker network inspect "${DOCKER_NETWORK_NAME}"

# If missing, create it
docker network create "${DOCKER_NETWORK_NAME}"

# Retry
./infra.sh restart <project>

Permission denied

bash ./deployment/scripts/utils/fix_permissions.sh
./infra.sh restart all

Port already in use

# Check which process is using the port
sudo lsof -i :<port>

# Change the port in .env
# Restart the service
./infra.sh restart <project>

Disk is full

# Remove unused containers/images
docker system prune -a

# Remove orphaned volumes
docker volume prune

# Show disk usage
docker system df

Next Step

See thingsboard.md and deployment.md for service-specific runtime and deployment details.

Main Script: infra.sh​

General Syntax​

Main Commands​

up - Start Services​

Start the full stack​

Start a specific project​

Start by folder paths​

down - Stop and Remove Containers​

Stop everything​

Stop a specific project​

Stop by paths​

clean - Cleanup Containers and Data​

Clean containers (preserve data)​

Clean EVERYTHING including data (DESTRUCTIVE)​

Clean a specific project​

restart - Restart Services​

Restart the full stack​

Restart a specific project​

Restart by paths​

status - Show Status​

Status of all projects​

Status of a specific project​

Status by paths​

logs - View Logs​

View core project logs​

View logs for a specific project​

View logs for a specific service​

View logs by paths​

build - Rebuild Images​

Rebuild all images​

Rebuild a specific project​

Rebuild by paths​

install - Initial Installation​

build-tb - Build Customized ThingsBoard​

Build normal​

generate-env - Environment Generation​

generate-configs - Generate Config Files​

fix-permissions - Fix Permissions​

test - Run Tests​

Ansible config test (fast, non-destructive)​

Docker infrastructure test (destructive)​

Available Projects​

Common Usage Examples​

Daily development​

ThingsBoard frontend development​

Debugging problems​

Testing and validation​

Maintenance​

Access URLs​

Important Environment Variables​

Ports​

Credentials (CHANGE IN PRODUCTION)​

Image versions​

Direct Docker Commands​

Troubleshooting​

Service does not start​

Permission denied​

Port already in use​

Disk is full​

Next Step​