1. 개요

본 문서는 다음 환경을 기준으로 ThingsBoard Community Edition(CE)을 구축하는 방법을 설명한다.

구성도

Internet
│
▼
Nginx Proxy Manager
│
▼
ThingsBoard (Docker)
│
├─ PostgreSQL
└─ Redis

사용 환경

• Ubuntu 22.04 LTS
• Docker
• Docker Compose
• Nginx Proxy Manager(NPM)
• Let’s Encrypt SSL
• ThingsBoard CE
• PostgreSQL
• Redis

예제 도메인

iot.example.com

본인의 도메인으로 변경하여 사용한다.

⸻

2. DNS 설정

도메인 관리 페이지에서 A 레코드를 추가한다.

타입 호스트 값
A iot 서버 공인IP

예시

iot.example.com
→ 123.123.123.123

DNS 전파 확인

nslookup iot.example.com

또는

dig iot.example.com

⸻

3. Docker 설치

패키지 업데이트

sudo apt update
sudo apt upgrade -y

Docker 설치

curl -fsSL https://get.docker.com | sudo sh

Docker Compose 확인

docker compose version

현재 사용자 권한 추가

sudo usermod -aG docker $USER

재로그인 후 확인

docker ps

⸻

4. 작업 폴더 생성

mkdir -p ~/thingsboard
cd ~/thingsboard

⸻

5. docker-compose.yml 작성

services:
postgres:
image: postgres:16
container_name: tb-postgres
restart: unless-stopped
environment:
POSTGRES_DB: thingsboard
POSTGRES_USER: thingsboard
POSTGRES_PASSWORD: tb_password
volumes:
- ./postgres:/var/lib/postgresql/data
networks:
- tb-net
redis:
image: redis:7
container_name: tb-redis
restart: unless-stopped
command: redis-server --appendonly yes
volumes:
- ./redis:/data
networks:
- tb-net
thingsboard:
image: thingsboard/tb-postgres:latest
container_name: thingsboard
restart: unless-stopped
depends_on:
- postgres
- redis
environment:
TB_QUEUE_TYPE: in-memory
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
SPRING_DATASOURCE_USERNAME: thingsboard
SPRING_DATASOURCE_PASSWORD: tb_password
REDIS_HOST: redis
REDIS_PORT: 6379
ports:
- "1883:1883"
- "5683:5683"
- "8080:9090"
volumes:
- ./tb-data:/data
- ./tb-logs:/var/log/thingsboard
networks:
- tb-net
networks:
tb-net:

⸻

6. ThingsBoard 실행

docker compose up -d

상태 확인

docker ps

⸻

7. ThingsBoard DB 초기화

최초 1회 실행

docker exec -it thingsboard bash

컨테이너 내부에서

/usr/bin/install/install.sh

설치 완료 후

exit

컨테이너 재시작

docker restart thingsboard

⸻

8. ThingsBoard 접속 확인

브라우저 접속

http://서버IP:8080

초기 관리자 계정

ID : sysadmin@thingsboard.org
PW : sysadmin

최초 로그인 후 반드시 비밀번호를 변경한다.

⸻

9. Nginx Proxy Manager 설정

NPM 관리자 페이지 접속

http://서버IP:81

기본 계정

admin@example.com
changeme

⸻

10. Proxy Host 생성

NPM 메뉴

Hosts
→ Proxy Hosts
→ Add Proxy Host

Domain Names

iot.example.com

Scheme

http

Forward Hostname

thingsboard

또는

서버IP

Forward Port

8080

옵션 체크

Websockets Support
Block Common Exploits

저장

⸻

11. Let’s Encrypt SSL 설정

생성한 Proxy Host 편집

SSL 탭 이동

SSL Certificate

Request a new SSL Certificate

체크

Force SSL
HTTP/2 Support
HSTS Enabled

이메일 입력 후 저장

예시

admin@example.com

정상 발급되면

https://iot.example.com

으로 접속 가능하다.

⸻

12. MQTT 포트 개방

방화벽 허용

sudo ufw allow 1883/tcp

MQTT TLS 사용 시

sudo ufw allow 8883/tcp

⸻

13. ThingsBoard MQTT 테스트

Device 생성

Devices
→ Add Device

Access Token 확인

Device Details
→ Copy Access Token

예시

abcd1234efgh5678

⸻

MQTT Publish 테스트

설치

sudo apt install mosquitto-clients -y

전송

mosquitto_pub
-h iot.example.com
-p 1883
-t v1/devices/me/telemetry
-u abcd1234efgh5678
-m '{"temperature":25}'

ThingsBoard Dashboard에서 데이터 수신 확인 가능.

⸻

14. 백업

PostgreSQL 백업

docker exec tb-postgres pg_dump
-U thingsboard
thingsboard \

backup.sql

복원

cat backup.sql | docker exec -i tb-postgres
psql -U thingsboard thingsboard

⸻

15. 업데이트

이미지 업데이트

docker compose pull
docker compose down
docker compose up -d

버전 확인

docker logs thingsboard

⸻

16. 추천 운영 설정

자동 재시작

이미 적용됨

restart: unless-stopped

로그 확인

docker logs -f thingsboard

리소스 확인

docker stats

데이터 백업 권장

postgres/
tb-data/
tb-logs/

정기적으로 백업한다.

⸻

완료

최종 접속 주소

https://iot.example.com

기본 관리자 계정

sysadmin@thingsboard.org
sysadmin

이제 HTTPS가 적용된 ThingsBoard IoT 플랫폼을 운영할 수 있다.