Environment Configuration (/ui/system/config) — Editing app.properties

This screen lets you edit the app.properties file — which holds all gateway settings (DB / MQTT / OPC-UA / site / monitoring / users, etc.) — directly from the web.

Click the Environment Configuration card on the home screen, or go to /ui/system/config.

Save behavior in container mode (2026.05+)

On save, /etc/kopens/app.properties (host bind mount) is updated and applied when the container restarts (/config/restart button or signal file /etc/kopens/host-action.request). For the HiveMQ broker, auth.properties is synchronized automatically with mqtt.server.* by the container-entrypoint on every boot — you only need to change app.properties (no manual editing of auth.properties required).

CLI change:

sudo bash /opt/kopens/install/bin/config.sh --set edge.rest.api.auth true
sudo bash /opt/kopens/install/bin/config.sh --restart

---

1. Screen Layout

┌─────────────────────────────────────────────────────────────┐
│              환경 설정              [←] [💾 저장]            │
├─────────────────────────────────────────────────────────────┤
│  ⚠ 주의사항 패널 (빨강)                                      │
│  - 환경 설정 파일 수정 시 서버 재시작 필요                    │
│  - 필수 키 삭제 금지                                         │
│  - 웹 접속 불가시 ${PE_HOME}/conf/app.properties 수동 수정     │
├─────────────────────────────────────────────────────────────┤
│  [CodeMirror 에디터 — properties 모드 / xq-dark 테마]        │
│   (라인번호, 매칭 괄호, 자동 완성, 활성 라인 하이라이트)      │
└─────────────────────────────────────────────────────────────┘

---

2. Top Actions

Button	Action
← Back	Go to /ui/main
💾 Save (blue button)	POST /config/save — save the current editor content to app.properties

Toast right after saving: "Configuration complete! Restart the server to apply the changes."

⚠ The save itself takes effect immediately, but the runtime only reflects it after a restart.

---

3. Editor — CodeMirror

Feature	Behavior
Mode	text/x-properties (KEY=VALUE format)
Theme	xq-dark (black background + neon keywords)
Line numbers	Shown on the left
Bracket matching	Auto-highlights ${...} and the like
Active line	Highlights the cursor line
Word wrap	Long lines wrap automatically
Height	2400px (long files at a glance)

---

4. Key app.properties Entries — The Ones You'll See Most

For details, see app.properties configuration. Frequently adjusted items:

Category	Key	Meaning
Operating mode	dev.mode	EDGE / STANDALONE / PLATFORM — usually EDGE on the edge
Site identification	edge.id	Gateway unique ID (EDGE_*)
	site.id / site.name	Site identification
Upstream platform	server.host / server.port / server.username	PlantPulse Platform API
	server.api_key (falls back to legacy server.apikey)	Token for token-based authentication (V4 setUsernameAndToken)
REST API authentication (external clients)	edge.rest.api.auth	If true, authentication is enforced on /api/* calls
	edge.rest.api.key	API key sent by external clients. In production, inject it via EDGE_REST_API_KEY_FILE / EDGE_REST_API_KEY and send it in the X-API-Key header or as Authorization: Bearer. A ?api_key= query is rejected with 401
OPC-UA server	opc.ua.server.host / tcp.port / user / password	The gateway's built-in OPC-UA server (external SCADA connects to it)
	opc.ua.server.anonymous	Allow Anonymous (yes/no/true/false/on/1) — the legacy misspelled key ananymous is also accepted as a fallback (both compatible)
MQTT	mqtt.enable / mqtt.server.host / port / user / password / topic	HiveMQ (built-in or external)
Sparkplug B	sparkplug.enable / sparkplug.cmd.enable / group.id / edge.node.id	Sparkplug publishing + NCMD/DCMD command reception
DB / TTL	app.db.scheme_ddl	DDL file path (default WEB-INF/db/scheme.cql — Cassandra CQL DDL)
	cassandra.host / port / keyspace / edge.ttl	Time series storage policy (TTL unit = days)
Monitoring	monitor.ping.targets	Internet ping target
Collection policy	collector.thread.size / collector.batch.size	Collector pool size
Security	security.session.timeout.minutes	Web session timeout

Deleting a required key / typo → boot failure

If a required key such as edge.id, cassandra.host, or mqtt.server.host is missing or malformed, the startup listener will fail on the next boot. If the web UI does not come up, SSH in, edit /opt/kopens/plantpulse-edge/conf/app.properties directly, then bin/restart.sh.

---

5. Applying Changes After Saving

1. [💾 저장] 클릭 → 토스트 "재시작 필요"
2. 외부 SCADA / Sparkplug 수신측에 점검 공지 (다운타임 ~6초)
3. SSH 또는 시스템 메뉴 → /config/restart 호출
4. 1–2초 대기 → 화면 새로고침 → /api/v1/edge 로 새 값 확인

For a quick restart, see Restart (restart.sh) (Tomcat only, ~6 s). Items that require a full restart including DB / MQTT (e.g. the mqtt.enable toggle) need a full restart (stop.sh → start.sh).

---

6. Common Pitfalls

Symptom	Cause / Resolution
Saved, but the change is not applied	Not restarted. Call bin/restart.sh
Web UI unreachable after saving	Required key deleted / typo. SSH in and recover manually
No toast right after saving	Communication error → check network / Tomcat status (bin/ps.sh)
Korean comments are garbled	The file is not UTF-8. Force UTF-8 (no BOM) in an external editor and save
The same key appears twice	The last occurrence wins. Delete the first line

---

7. System Tags (auto-registered / 90000–90035)

At boot, the gateway automatically registers its own OPC (EDGE_*) and 36 system tags (TAG_<edge_id>_NNNNN) in the OPC-UA server. If an external SCADA / IIoT system subscribes to these tags, it receives the gateway's status/identity/network information directly.

7.1 Identity / Host (90000–90004)

Index	Metric	Type	Meaning
90000	HOSTNAME	STRING	OS hostname
90001	VERSION	STRING	Gateway SW version
90002	EDGE_IP	STRING	Gateway's own IP
90003	EDGE_NAME	STRING	Gateway name
90004	OPERATING_SYSTEM	STRING	OS + architecture

7.2 Network (90005–90011)

Index	Metric	Type	Meaning
90005	NET_1_IP	STRING	NIC 1 IP
90006	NET_2_IP	STRING	NIC 2 IP
90007	NET_WIFI_IP	STRING	WIFI IP
90008	NET_GSM_IP	STRING	GSM modem IP
90009	NET_VPN_IP	STRING	VPN (tailscale, etc.) IP
90010	NET_MGNT_IP	STRING	Management port IP
90011	TEMPERATURE	DOUBLE	CPU temperature (°C)

7.3 System / Collection / Queue (90012–90027)

Index	Metric	Type	Meaning
90012	CPU_USAGE	DOUBLE	CPU %
90013	MEM_USAGE	DOUBLE	Memory %
90014	DISK_USAGE	DOUBLE	Disk %
90015	OPC_COUNT	INT	Number of registered OPCs
90016	TAG_COUNT	INT	Number of registered tags
90017	PLC_CON_CONNECTED_COUNT	INT	Number of connected OPCs
90018	PLC_CON_DISCONNECTED_COUNT	INT	Number of disconnected OPCs
90019	PLC_SCAN_START_COUNT	INT	Number of OPCs collecting normally
90020	PLC_SCAN_NOT_COLLECT_COUNT	INT	Number of OPCs with collection faults
90021	PLC_SCAN_STOP_COUNT	INT	Number of OPCs with collection stopped
90022	QUEUE_SIZE	INT	Memory queue
90023	QUEUE_DISK_SIZE	INT	Disk queue
90024	SENDED_POINT_COUNT	LONG	Cumulative transmitted points
90025	SENDED_POINT_BYTES	LONG	Cumulative transmitted bytes
90026	MPS	DOUBLE	Messages per second
90027	SYSTEM_ERROR_COUNT	INT	ERROR count today

7.4 Operations / Identity (90028–90035) — new

Index	Metric	Type	Meaning
90028	CONNECTED_OPC_IDS	STRING	List of connected OPC IDs (comma-separated)
90029	API_KEY	STRING	Currently active REST API key
90030	REGISTED_OPC_IDS	STRING	List of all registered OPC IDs
90031	DISCONNECTED_OPC_IDS	STRING	List of disconnected OPC IDs
90032	COLLECTING_OPC_IDS	STRING	List of OPC IDs currently collecting
90033	STOPPED_OPC_IDS	STRING	List of OPC IDs with collection stopped
90034	BUILD_DATE	STRING	Build date of the artifact (yyyy-MM-dd)
90035	DOCKER_CONTAINER_NAMES	STRING	Names of running Docker containers (comma-separated)

All system tags are refreshed every second by SendTask. If an external SCADA subscribes to them, you can build a dashboard that shows edge status at a glance without going to the field.

---

8. Learn More

• Meaning of every key: app.properties configuration
• Restarting after changes: Restart (restart.sh)
• Changing after a backup: Backup (backup.sh)
• Verifying changes via system logs: Viewing system logs
• REST API authentication / key issuance: REST API guide