hansjone/netx
1
0
Fork 0
mirror of https://github.com/hansjone/netx.git synced 2026-10-09 00:50:46 +08:00
Code Issues Projects Releases 1 Packages Wiki Activity Actions 2

docs: document full environment setup and enforce venv startup

Browse source 
Add a from-scratch setup section covering Python, Node/npm, PostgreSQL, and startup commands, and update the startup script to always create/use .venv instead of falling back to system Python.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
oliver 2026-05-03 23:53:24 +08:00
parent e50c0b1f0b
commit f718807fa4
2 changed files with 60 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

84
README.md
View file

@ -11,15 +11,50 @@ Independent operations tool (web + MCP) for alarm-centric workflows.
- Quick diagnostics endpoint (`/v1/diagnostics`)
- AP analysis bridge to oclaw (`/v1/ap/analyze`)
## Run locally
## Environment setup (from scratch)
1. Install dependencies:
### 0) Prerequisites
- Python `3.11+` (project currently tested on newer versions too)
- Node.js `20+` (includes npm) for frontend
- PostgreSQL `14+`
- PowerShell (Windows startup scripts use `.ps1`)
Quick check:
```powershell
python -m pip install -r requirements.txt
python --version
node --version
npm --version
psql --version
```
2. Set environment variables:
If Node/npm is missing (Windows example):
```powershell
winget install OpenJS.NodeJS.LTS
```
### 1) Python virtual environment and backend deps
```powershell
cd netx
python -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -r requirements.txt
```
### 2) Frontend deps (npm)
```powershell
cd .\web
npm install
cd ..
```
### 3) Configure environment variables
Option A: temporary env vars in current shell
```powershell
$env:NETX_DATABASE_URL = "postgresql+psycopg://netx:netx@127.0.0.1:5432/netx"
@ -27,7 +62,7 @@ $env:NETX_HOST = "127.0.0.1"
$env:NETX_PORT = "8890"
```
Or create a local `.env` (recommended for persistent local run):
Option B: local `.env` (recommended)
```env
NETX_DATABASE_URL=postgresql+psycopg://postgres:admin123@127.0.0.1:5432/netx
@ -35,25 +70,29 @@ NETX_OCLAW_ANALYZE_TOKEN=admin123
NETX_OCLAW_HEALTH_URL=http://127.0.0.1:8787/admin/api/ops-ai/health
```
3. Start API:
### 4) Start services
Direct backend start:
```powershell
python -m netx_api.main
.\.venv\Scripts\python -m netx_api.main
```
Or use automation scripts:
Or use automation scripts (recommended):
- API only (background):
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start_netx.ps1 -SkipInstall -Background
```
Start API + Vite together:
- API + Vite UI (background):
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start_netx.ps1 -SkipInstall -Background -WithWeb
```
Stop:
Stop all started services:
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\stop_netx.ps1 -Force
@ -62,35 +101,16 @@ powershell -ExecutionPolicy Bypass -File .\scripts\stop_netx.ps1 -Force
Primary web UI (Vite): `http://127.0.0.1:5173/`
API base: `http://127.0.0.1:8890/`
4. Optional: start MCP server (for oclaw integration):
### 5) Optional: MCP server (for oclaw integration)
```powershell
python -m netx_api.mcp_server
.\.venv\Scripts\python -m netx_api.mcp_server
```
Or use MCP install payload:
Or install via payload:
- `netx/mcp_install_payload.json`
## Industrial UI (Vite + React + TS)
Frontend project lives in:
- `netx/web`
Run:
```powershell
cd web
npm install
npm run dev
```
Dev server: `http://127.0.0.1:5173`
`vite.config.ts` proxies `/v1/*` to `http://127.0.0.1:8890`.
`8890` is API-only and no longer serves the main UI page.
## Useful API endpoints
- `POST /v1/alarms/import`