Local Development¶

Use this setup when you want fast iteration, debugging, and direct access to backend/frontend processes.

flowchart LR
  A[Prepare env] --> B[Run PostgreSQL]
  B --> C[Start backend]
  C --> D[Start frontend]
  D --> E[Run optional agent]
  E --> F[Verify login and wake flow]
  style A fill:#2563eb,stroke:#1e3a8a,color:#fff
  style F fill:#16a34a,stroke:#166534,color:#fff

Prerequisites¶

• Python 3.13+
• Node.js 20+
• PostgreSQL 16+
• Git

1. Clone and Configure¶

1
2

git clone https://github.com/kotsiossp97/powerbeacon.git
cd powerbeacon

Create root environment file:

Linux/macOS:

1

cp .env.example .env

PowerShell:

1

Copy-Item .env.example .env

2. Start PostgreSQL¶

Ensure PostgreSQL is running and create a powerbeacon database with user credentials matching your DB_URL.

Recommended local URL:

DB_URL=postgresql+psycopg2://powerbeacon:changeMe@localhost:5432/powerbeacon

3. Run Backend (FastAPI)¶

From repository root:

1
2

cd backend
uv run fastapi dev main.py --host 0.0.0.0 --port 8000

Alternatively, using pip:

1
2
3
4
5

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
fastapi dev main.py --host 0.0.0.0 --port 8000

1
2
3
4
5

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
fastapi dev main.py --host 0.0.0.0 --port 8000

Backend URLs:

• API: http://localhost:8000
• Swagger: http://localhost:8000/api/docs
• Health: http://localhost:8000/health

4. Run Frontend (Vite)¶

Open a second terminal from repository root:

1
2
3

cd frontend
npm install
npm run dev

Frontend URL:

• http://localhost:5173

If needed, configure API base URL in frontend environment to point at http://localhost:8000.

5. Agent Development (Optional)¶

From repository root:

cd agent
go mod download
go test ./...

Build local binaries:

go build -o build/powerbeacon-agent ./cmd/agent

6. Verification Checklist¶

1. Backend health endpoint returns ok.
2. Frontend loads without runtime errors.
3. Login works.
4. Device list API returns data.
5. Wake action request is accepted by backend.

Useful Commands¶

Backend formatting and linting:

cd backend
uv run ruff check --fix
uv run ruff format

Frontend lint/build:

cd frontend
npm run lint
npm run build

Agent tests:

cd agent
go test ./...

Troubleshooting¶

CORS issues in browser¶

Confirm backend CORS allows http://localhost:5173 or your active frontend origin.

DB connection errors¶

Confirm PostgreSQL is running and DB_URL points to correct host, user, password, and database.

Frontend cannot reach backend¶

1. Confirm backend is running on port 8000.
2. Confirm frontend API base URL is set correctly.
3. Check browser network tab for failing requests.

Authentication problems¶

For local mode, verify:

JWT_SECRET=<non-default-secret>

For OIDC, verify issuer/client settings in .env and that provider endpoints are reachable.

Next Step¶

Return to Setup Overview or continue to architecture docs.