Getting Started

Getting Started

This guide gets you from clone to a running local stack.

When To Use This Page

Use this page for first-time local startup and health validation before deeper user or developer workflows.

Audience

• New users who want to run the platform locally.
• New developers who need a known-good baseline before coding.

Prerequisites

• Docker Engine + Docker Compose plugin.
• At least 8 GB RAM available for Docker.
• Ports available on host: 5173, 8000, 8001, 18083, 8025, 1025, 5432, 1883, 1884.

1. Configure Environment Variables

1. Go to project-code/.
2. Open .env and set at least:

• EMQX_DASHBOARD_PASSWORD to a strong value.
• JWT_SECRET and JWT_VERIFICATION_SECRET to at least 32 bytes (256 bits) of cryptographically secure random data.
• SUPERUSER_MAIL to the admin mailbox you want to use.

Generation examples:

openssl rand -hex 32

$bytes = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes); [Convert]::ToHexString($bytes).ToLower()

Use Environment Variables for full catalog and validation guidance.

2. Start The Stack

From project-code/:

docker compose up -d --build

3. Verify The Stack

docker compose ps

Expected core services in Up/healthy: frontend, api-gateway, tactic-middleware, timescaledb, emqx-main, mqtt-proxy, db-sync, mailpit.

Quick checks:

curl http://localhost:8000/health
curl http://localhost:8001/ready

Open in browser:

• Frontend: http://localhost:5173
• Mailpit: http://localhost:8025
• EMQX dashboard: http://localhost:18083

4. Create First User

1. Register in frontend.
2. Open Mailpit and copy verification link.
3. Verify email.
4. Log in and open charger list.

5. Shutdown / Reset

Stop containers:

docker compose down

Full reset (containers + volumes):

docker compose down -v

Common First-Run Issues

Symptom	Likely Cause	Fix
api-gateway keeps restarting	db-sync not ready or DB startup delay	wait 1-2 min, then check docker compose logs db-sync api-gateway
EMQX fails healthcheck	missing/weak dashboard password	set EMQX_DASHBOARD_PASSWORD, restart EMQX
Verification emails not visible	Mailpit not running	check mailpit and open http://localhost:8025
Frontend cannot reach API	VITE_API_URL mismatch for run mode	align VITE_API_URL with runtime mode

Related Pages

• User Guide - Web App
• Developer Setup
• Deployment Modes
• Testing & Debugging