Spaces:
Paused
Paused
File size: 2,390 Bytes
5a81b95 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | # Codespace Quickstart (GitHub Codespaces)
WidgeTDC is fully configured for GitHub Codespaces with auto-start of all services.
## Quick Start (Auto-Start)
1. **Create Codespace**: Click **Code > Create codespace on main**
2. **Wait for setup**: The devcontainer automatically:
- Installs dependencies
- Configures PostgreSQL + pgvector, Redis, Neo4j
- Generates Prisma client and syncs database
- Starts backend (port 3001) and frontend (port 5173)
3. **Open the app**: Click the forwarded port 5173 notification
That's it! The system is running.
## Manual Control
### Check service status
```bash
# View logs
tail -f .devcontainer/logs/backend.log
tail -f .devcontainer/logs/frontend.log
# Health check
curl http://localhost:3001/health
```
### Restart services
```bash
# Stop running services
pkill -f "node.*backend" || true
pkill -f "vite" || true
# Start again
bash .devcontainer/start-services.sh
```
### Run in foreground (for debugging)
```bash
# Terminal 1: Backend
cd apps/backend && npm run dev
# Terminal 2: Frontend
cd apps/matrix-frontend && npm run dev -- --host 0.0.0.0
```
## Services & Ports
| Service | Port | URL |
|---------|------|-----|
| Frontend (Vite) | 5173 | Auto-opens in browser |
| Backend API | 3001 | `http://localhost:3001` |
| Neo4j Browser | 7474 | `http://localhost:7474` |
| PostgreSQL | 5432 | Internal only |
| Redis | 6379 | Internal only |
## Environment Configuration
The Codespace uses `.env.codespace` which is auto-copied to `.env`:
- **PostgreSQL**: `postgres:5432` with pgvector extension
- **Redis**: `redis:6379`
- **Neo4j**: `neo4j:7687` (user: neo4j, pass: password)
- **Embeddings**: Local Transformers.js (no API key needed)
To add AI keys, edit `apps/backend/.env`:
```bash
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
```
## Recommended Codespace Size
- **Minimum**: 4-core / 8 GB RAM / 32 GB disk
- **Recommended**: 8-core / 16 GB RAM (faster builds)
## Troubleshooting
### Database connection failed
```bash
# Check if PostgreSQL is running
docker ps | grep postgres
# Restart data services
docker compose -f .devcontainer/docker-compose.yml restart postgres redis neo4j
```
### Frontend won't start
```bash
cd apps/matrix-frontend
npm install
npm run dev -- --host 0.0.0.0
```
### Backend build errors
```bash
npm run build:shared # Build shared packages first
cd apps/backend && npm run build
```
|