Skip to main content

Quick Reference

Quick Commands​

Full testing​

./infra.sh test infra

Kafka diagnostics​

# Check Kafka full status
./deployment/scripts/diagnose_kafka.sh

# Fix permissions automatically
./deployment/scripts/diagnose_kafka.sh fix-perms

# Test message production/consumption
./deployment/scripts/diagnose_kafka.sh test-msg

Quick Fixes​

Kafka does not start (permissions error)​

./deployment/scripts/diagnose_kafka.sh fix-perms
./infra.sh restart kafka

ThingsBoard asks to run install after an update​

# Check whether the flag exists
ls -la platform/thingsboard/.installed

# If missing, reinstall
./infra.sh install thingsboard

Check all services status​

./infra.sh status all

View logs for a specific service​

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

Workflows​

First installation​

# 1. Generate configs
bash ./deployment/scripts/config-generators/generate-configs.sh

# 2. Install ThingsBoard
./infra.sh install thingsboard

# 3. Bring everything up
./infra.sh up all

# 4. Verify status
./infra.sh status all

System update​

# 1. Stop services
./infra.sh down all

# 2. Update code (git pull, etc.)
git pull

# 3. Start services again (NO reinstall needed)
./infra.sh up all

# 4. Verify status
./infra.sh status all

Full cleanup and reinstall​

# 1. Clean everything (including data)
./infra.sh clean all --data

# 2. Reinstall ThingsBoard
./infra.sh install thingsboard

# 3. Bring everything up
./infra.sh up all

Quick Validation Checklist​

After installation​

  • docker ps shows kafka, zookeeper, thingsboard running
  • ./infra.sh status all shows all services "Up"
  • ThingsBoard is reachable at http://localhost:9090
  • Kafka UI is reachable at http://localhost:8080 (if enabled)
  • No errors in ./infra.sh logs kafka
  • No errors in ./infra.sh logs thingsboard

After update​

  • ls -la platform/thingsboard/.installed exists
  • Services start without running install
  • Data persists (users, dashboards, etc.)
  • No errors in logs

Kafka permissions​

  • ./deployment/scripts/diagnose_kafka.sh reports permissions OK
  • Kafka and Zookeeper are "healthy"
  • Topics can be created
  • Messages can be produced/consumed

Quick Troubleshooting​

SymptomLikely causeFix
Kafka restarts continuouslyWrong permissions./deployment/scripts/diagnose_kafka.sh fix-perms
ThingsBoard asks to installMissing .installed./infra.sh install thingsboard
Docker network missingMissing ${DOCKER_NETWORK_NAME}source .env && docker network create "${DOCKER_NETWORK_NAME}"
Port already in usePort conflictEdit .env / deployment/topology.env and restart
Permission deniedVolume permissionsbash ./deployment/scripts/utils/fix_permissions.sh

Full Documentation​

Tips​

  1. Always run ./infra.sh status all before reporting an issue
  2. Logs are your friend: ./infra.sh logs <service> will show what's wrong
  3. Kafka diagnostics are safe: you can run them at any time
  4. Clean vs Clean --data: clean preserves data, clean --data deletes it
  5. The .installed flag matters: don't delete it unless you want to reinstall

Last updated: 2025-12-10