171 lines
3.8 KiB
Markdown
171 lines
3.8 KiB
Markdown
# Quick Start Guide - Gold Trading Simulator
|
|
|
|
Get up and running in 5 minutes!
|
|
|
|
## Prerequisites Checklist
|
|
|
|
- [ ] Node.js 18+ installed (`node --version`)
|
|
- [ ] Python 3.11+ installed (`python --version`)
|
|
- [ ] Docker installed (`docker --version`)
|
|
- [ ] Alpha Vantage API key (get free at https://www.alphavantage.co/support/#api-key)
|
|
- [ ] OpenRouter API key (get at https://openrouter.ai/)
|
|
|
|
## 5-Minute Setup
|
|
|
|
### 1. Start Database (1 minute)
|
|
|
|
```bash
|
|
cd gold-trading-simulator
|
|
docker-compose up -d
|
|
```
|
|
|
|
Wait for PostgreSQL to start:
|
|
```bash
|
|
docker logs gold_trading_db
|
|
# Should see: "database system is ready to accept connections"
|
|
```
|
|
|
|
### 2. Setup Backend (2 minutes)
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Configure environment
|
|
cp .env.example .env
|
|
nano .env # or use your preferred editor
|
|
```
|
|
|
|
**Edit `.env` and add your API keys:**
|
|
```bash
|
|
ALPHA_VANTAGE_API_KEY=your_actual_key_here
|
|
OPENROUTER_API_KEY=your_actual_key_here
|
|
```
|
|
|
|
**Initialize database:**
|
|
```bash
|
|
python ../database/init_db.py
|
|
```
|
|
|
|
### 3. Setup Frontend (1 minute)
|
|
|
|
```bash
|
|
cd ../frontend
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Environment already configured in .env.example
|
|
# No changes needed unless you changed backend port
|
|
```
|
|
|
|
### 4. Start Application (1 minute)
|
|
|
|
**Terminal 1 - Backend:**
|
|
```bash
|
|
cd backend
|
|
source venv/bin/activate
|
|
python -m app.main
|
|
```
|
|
|
|
You should see:
|
|
```
|
|
INFO: Uvicorn running on http://0.0.0.0:8000
|
|
```
|
|
|
|
**Terminal 2 - Frontend:**
|
|
```bash
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
You should see:
|
|
```
|
|
VITE v5.x.x ready in XXX ms
|
|
|
|
➜ Local: http://localhost:3000/
|
|
```
|
|
|
|
### 5. Open Browser
|
|
|
|
Navigate to: **http://localhost:3000**
|
|
|
|
You should see the Gold Trading Simulator dashboard!
|
|
|
|
## First Steps in the App
|
|
|
|
1. **Wait for data to load** - The chart will populate with gold price history
|
|
2. **Explore the chart** - Hover over candles to see price details
|
|
3. **Execute a trade:**
|
|
- Enter quantity (e.g., 10 oz)
|
|
- Click "Buy" button
|
|
- See position appear in portfolio
|
|
4. **Try AI analysis:**
|
|
- Click "AI Analysis" button
|
|
- Wait ~5-10 seconds
|
|
- Review recommendation
|
|
|
|
## Troubleshooting
|
|
|
|
### "Error loading market data"
|
|
- **Check:** Alpha Vantage API key in `backend/.env`
|
|
- **Verify:** Backend is running on port 8000
|
|
- **Test:** `curl http://localhost:8000/health`
|
|
|
|
### "Backend connection failed"
|
|
- **Check:** Backend terminal for errors
|
|
- **Verify:** No other service using port 8000
|
|
- **Test:** `curl http://localhost:8000/api/market/gold/current`
|
|
|
|
### "AI analysis failed"
|
|
- **Check:** OpenRouter API key in `backend/.env`
|
|
- **Verify:** You have credits at https://openrouter.ai/
|
|
- **Check:** Backend logs for detailed error
|
|
|
|
### Database connection error
|
|
- **Check:** Docker container is running: `docker ps`
|
|
- **Restart:** `docker-compose restart`
|
|
- **Logs:** `docker logs gold_trading_db`
|
|
|
|
## API Key Setup Details
|
|
|
|
### Alpha Vantage (Free Tier)
|
|
1. Visit: https://www.alphavantage.co/support/#api-key
|
|
2. Enter your email
|
|
3. Get instant API key
|
|
4. **Limits:** 500 calls/day, 5 calls/minute
|
|
5. **Cost:** Free forever
|
|
|
|
### OpenRouter
|
|
1. Visit: https://openrouter.ai/
|
|
2. Sign up with GitHub/Google
|
|
3. Go to Keys section
|
|
4. Create new key
|
|
5. Add credits ($5 minimum)
|
|
6. **Cost:** ~$0.01-0.05 per AI analysis
|
|
|
|
## Next Steps
|
|
|
|
- Read [README.md](README.md) for full documentation
|
|
- Explore different trading strategies
|
|
- Check out the API endpoints
|
|
- Plan Phase 2 features (multiple timeframes, more indicators)
|
|
|
|
## Getting Help
|
|
|
|
If you run into issues:
|
|
1. Check the Troubleshooting section above
|
|
2. Review backend logs in the terminal
|
|
3. Check browser console for frontend errors (F12)
|
|
4. Verify all environment variables are set correctly
|
|
|
|
---
|
|
|
|
Happy Trading! (Virtually, of course!)
|