Repository navigation
Development
This page covers setting up a local development environment, code conventions, and how to contribute to AzerothPanel.
- Local setup (no Docker)
- Backend development
- Frontend development
- Code style & conventions
- Adding a new API endpoint
- Adding a new frontend page
- Validation checklist
- Python 3.11+
- Node.js 20 LTS + npm
- A running AzerothCore MySQL instance accessible from your machine
- (Optional) A running worldserver for SOAP commands
git clone https://github.com/scarecr0w12/AzerothPanel.git
cd AzerothPanel
make install # installs backend + frontend deps
cp backend/.env.example backend/.env
# Set SECRET_KEY, PANEL_ADMIN_USER, PANEL_ADMIN_PASSWORD in backend/.env
make dev # starts both processes with hot-reload- Backend:
http://localhost:8000 - Frontend:
http://localhost:5173(Vite HMR) - Swagger UI:
http://localhost:8000/docs
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtuvicorn app.main:app --reload --host 0.0.0.0 --port 8000backend/app/
├── main.py # App factory: registers routers, CORS, lifespan event
├── core/
│ ├── config.py # Pydantic BaseSettings — all env vars typed here
│ ├── database.py # Async SQLAlchemy engine + session factory + migrations
│ └── security.py # JWT create/verify, password hashing, get_current_user
├── models/
│ ├── panel_models.py # SQLAlchemy ORM models (PanelSettings, etc.)
│ └── schemas.py # Pydantic schemas for request/response bodies
├── api/v1/
│ ├── router.py # Aggregates all endpoint routers under /api/v1
│ └── endpoints/ # One file per feature domain
├── api/websockets/
│ └── logs.py # WebSocket handler for live log tailing
└── services/
├── panel_settings.py # CRUD helpers for panel settings
└── azerothcore/
├── server_manager.py # Process start/stop
├── compiler.py # Runs cmake/make, yields output lines
├── installer.py # Runs AzerothCore installation steps
├── soap_client.py # HTTP SOAP client (httpx)
└── module_manager.py # Git-based module install/remove
- Activate the venv:
source backend/.venv/bin/activate - Install:
pip install <package> - Freeze:
pip freeze > backend/requirements.txt
Schema changes are applied via ALTER TABLE statements in backend/app/core/database.py:run_panel_db_migrations() guarded by try/except. This runs on every startup. To add a new column:
try:
await conn.execute(text("ALTER TABLE my_table ADD COLUMN new_col TEXT"))
except Exception:
pass # column already existscd frontend
npm install
npm run devThe Vite config proxies /api/ and /ws/ to http://localhost:8000.
cd frontend
npm run build # outputs to frontend/dist/frontend/src/
├── App.tsx # React Router routes
├── main.tsx # Entry point
├── index.css # Tailwind base
├── pages/ # Full-page views (one per route)
├── components/
│ ├── layout/ # Header, Sidebar, Layout wrapper
│ └── ui/ # Reusable primitives (Button, Card, StatusBadge)
├── hooks/
│ ├── useWebSocket.ts # Generic WebSocket hook with reconnect
│ └── useServerStatus.ts
├── services/api.ts # Axios instance + all typed API calls
├── store/index.ts # Zustand global store (auth token, server state)
└── types/index.ts # Shared TypeScript interfaces
- Follow PEP 8; use 4-space indentation.
- Use
async deffor all route handlers and service functions. - All request/response bodies are typed with Pydantic schemas in
models/schemas.py. - Raise
HTTPExceptionwith appropriate status codes; do not return raw error strings. - Business logic belongs in
services/, not in endpoint handlers. - Use dependency injection (
Depends) for auth, database sessions, and settings.
- TypeScript strict mode is enabled — no
anytypes without justification. - Functional components with hooks only; no class components.
- API calls live in
services/api.ts; pages do not callaxiosdirectly. - Shared types go in
types/index.ts. - Use Tailwind utility classes; avoid custom CSS unless unavoidable.
-
Create or update the endpoint file in
backend/app/api/v1/endpoints/:# backend/app/api/v1/endpoints/example.py from fastapi import APIRouter, Depends from app.core.security import get_current_user router = APIRouter(prefix="/example", tags=["Example"]) @router.get("/hello") async def hello(_: dict = Depends(get_current_user)): return {"message": "Hello from the new endpoint"}
-
Register it in the router (
backend/app/api/v1/router.py):from app.api.v1.endpoints import example api_router.include_router(example.router)
-
Add Pydantic schemas to
backend/app/models/schemas.pyif needed. -
Expose it in the frontend (
frontend/src/services/api.ts):export const getHello = () => api.get<{ message: string }>("/example/hello").then(r => r.data);
-
Create the page component in
frontend/src/pages/MyPage.tsx. -
Add the route in
frontend/src/App.tsx:import MyPage from "./pages/MyPage"; // inside <Routes>: <Route path="/my-page" element={<MyPage />} />
-
Add a sidebar link in
frontend/src/components/layout/Sidebar.tsx:{ path: "/my-page", label: "My Page", icon: <SomeIcon /> }
Before committing, verify:
-
TypeScript type check (must be zero errors):
cd frontend && npx tsc --noEmit
-
Frontend production build (must succeed):
cd frontend && npm run build
-
Python syntax check for any modified files:
cd backend && source .venv/bin/activate python -m py_compile app/main.py
There are no automated tests in this project. Manual validation is required.