branderson
4130adfe58
A new README for the combined project with setup from the Flashpoint Ultimate torrent. New feature docs for streaming, proxy sign-in and game saves; deployment, upgrade and streaming READMEs updated for the single compose file; the project renamed throughout.
268 lines
4.8 KiB
Markdown
268 lines
4.8 KiB
Markdown
# Development Setup Guide
|
|
|
|
Complete guide to setting up Dotcom Arcade development environment.
|
|
|
|
## Prerequisites
|
|
|
|
### Required Software
|
|
|
|
**Node.js v20.0.0+**
|
|
|
|
```bash
|
|
node --version # Verify
|
|
nvm install 20 && nvm use 20 # Install with nvm
|
|
```
|
|
|
|
**npm v9.0.0+** (included with Node.js)
|
|
|
|
```bash
|
|
npm --version # Verify
|
|
```
|
|
|
|
**Git**
|
|
|
|
```bash
|
|
git --version # Verify
|
|
```
|
|
|
|
**Flashpoint Archive**
|
|
|
|
- Download from [flashpointarchive.org](https://flashpointarchive.org/)
|
|
- Default path: `D:\Flashpoint` (Windows) or `~/Flashpoint` (Linux/Mac)
|
|
- Verify: `ls D:/Flashpoint/Data/flashpoint.sqlite`
|
|
|
|
---
|
|
|
|
## Initial Setup
|
|
|
|
### 1. Clone Repository
|
|
|
|
```bash
|
|
git clone <repository-url> dotcom-arcade
|
|
cd dotcom-arcade
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
|
|
```bash
|
|
npm run install:all
|
|
|
|
# This runs npm install in root, backend/, and frontend/
|
|
```
|
|
|
|
### 3. Configure Backend
|
|
|
|
```bash
|
|
cd backend
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `backend/.env`:
|
|
|
|
```bash
|
|
FLASHPOINT_PATH=D:/Flashpoint
|
|
JWT_SECRET=change-this-in-production
|
|
|
|
# Optional
|
|
DOMAIN=http://localhost:5173
|
|
LOG_LEVEL=info
|
|
NODE_ENV=development
|
|
```
|
|
|
|
**Note:** All paths (database, images, logos, htdocs, games) are automatically
|
|
derived from `FLASHPOINT_PATH`.
|
|
|
|
### 4. Verify Setup
|
|
|
|
```bash
|
|
npm run typecheck # Type check all services
|
|
npm run build # Build all services
|
|
```
|
|
|
|
---
|
|
|
|
## Start Development
|
|
|
|
### Option A: All Services Together
|
|
|
|
```bash
|
|
npm run dev
|
|
|
|
# Expected output:
|
|
# [backend] Server running on port 3100
|
|
# [frontend] Local: http://localhost:5173/
|
|
```
|
|
|
|
### Option B: Individual Services
|
|
|
|
```bash
|
|
# Terminal 1: Backend
|
|
npm run dev:backend
|
|
|
|
# Terminal 2: Frontend
|
|
npm run dev:frontend
|
|
```
|
|
|
|
### Verify Services
|
|
|
|
```bash
|
|
# Backend
|
|
curl http://localhost:3100/health # Should return {"status":"ok"}
|
|
|
|
# Frontend
|
|
# Open http://localhost:5173 in browser
|
|
```
|
|
|
|
---
|
|
|
|
## Test Basic Functionality
|
|
|
|
1. Open http://localhost:5173
|
|
2. Browse games in library
|
|
3. Search for a game
|
|
4. Register a test user
|
|
5. Login
|
|
6. Try playing a Flash game
|
|
|
|
---
|
|
|
|
## IDE Setup (Optional)
|
|
|
|
### Visual Studio Code
|
|
|
|
**Install Recommended Extensions:**
|
|
|
|
- ESLint
|
|
- Prettier
|
|
- TypeScript Language Features
|
|
- Tailwind CSS IntelliSense
|
|
- REST Client
|
|
- SQLite Viewer
|
|
|
|
**Settings (.vscode/settings.json):**
|
|
|
|
```json
|
|
{
|
|
"editor.formatOnSave": true,
|
|
"editor.codeActionsOnSave": {
|
|
"source.fixAll.eslint": true
|
|
},
|
|
"typescript.tsdk": "node_modules/typescript/lib",
|
|
"typescript.enablePromptUseWorkspaceTsdk": true
|
|
}
|
|
```
|
|
|
|
**Debug Configuration (.vscode/launch.json):** See
|
|
[Debugging Guide](./debugging.md) for complete setup.
|
|
|
|
### WebStorm/IntelliJ
|
|
|
|
1. Set Node interpreter to Node 20+
|
|
2. Enable ESLint (File > Settings > ESLint)
|
|
3. Create run configurations for backend and frontend
|
|
|
|
---
|
|
|
|
## Before First Commit
|
|
|
|
```bash
|
|
npm run typecheck # Check types
|
|
npm run build # Build all
|
|
cd backend && npm run lint && npm test # Lint and test
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Already in Use
|
|
|
|
```bash
|
|
cd backend
|
|
npm run kill-port # Windows utility
|
|
```
|
|
|
|
### Database Not Found
|
|
|
|
```bash
|
|
# Verify Flashpoint path
|
|
ls D:/Flashpoint/Data/flashpoint.sqlite
|
|
|
|
# Check backend/.env
|
|
cat backend/.env | grep FLASHPOINT_PATH
|
|
```
|
|
|
|
### Dependencies Won't Install
|
|
|
|
```bash
|
|
npm cache clean --force
|
|
npm run clean
|
|
npm run install:all
|
|
```
|
|
|
|
### Ruffle Not Loading
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run copy-ruffle
|
|
|
|
# Verify files exist
|
|
ls public/ruffle/
|
|
```
|
|
|
|
See [Common Pitfalls](./common-pitfalls.md) for more issues.
|
|
|
|
---
|
|
|
|
## Environment Variables Reference
|
|
|
|
### Backend (.env)
|
|
|
|
| Variable | Required | Default |
|
|
| ----------------- | -------- | --------------------- |
|
|
| `FLASHPOINT_PATH` | Yes | - |
|
|
| `JWT_SECRET` | Yes\* | - |
|
|
| `DOMAIN` | No | http://localhost:5173 |
|
|
| `LOG_LEVEL` | No | info |
|
|
| `NODE_ENV` | No | development |
|
|
|
|
### Frontend
|
|
|
|
No environment variables required for local development.
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Read [Project Structure](./project-structure.md)
|
|
2. Read [Commands Reference](./commands.md)
|
|
3. Read [Coding Standards](./coding-standards.md)
|
|
4. Read [Common Pitfalls](./common-pitfalls.md)
|
|
5. Start making contributions!
|
|
|
|
---
|
|
|
|
## Development Checklist
|
|
|
|
- [ ] Node.js 20+ installed
|
|
- [ ] npm 9+ installed
|
|
- [ ] Flashpoint Archive installed
|
|
- [ ] Repository cloned
|
|
- [ ] Dependencies installed (`npm run install:all`)
|
|
- [ ] Backend .env configured
|
|
- [ ] All services type check pass (`npm run typecheck`)
|
|
- [ ] All services build successfully (`npm run build`)
|
|
- [ ] Backend starts successfully
|
|
- [ ] Frontend accessible at http://localhost:5173
|
|
- [ ] Can browse and play games
|
|
|
|
---
|
|
|
|
## Additional Resources
|
|
|
|
- [Commands Reference](./commands.md)
|
|
- [Debugging Guide](./debugging.md)
|
|
- [Testing Guide](./testing-guide.md)
|
|
- [Coding Standards](./coding-standards.md)
|
|
- [Common Pitfalls](./common-pitfalls.md)
|