257 lines
7.7 KiB
Markdown
257 lines
7.7 KiB
Markdown
# Pokedex Online
|
|
|
|
A modern Vue 3 web application for Pokemon Professors to manage tournaments, process gamemaster data, and handle tournament printing materials.
|
|
|
|
## Features
|
|
|
|
- **Gamemaster Manager** - Fetch Pokemon GO gamemaster data from PokeMiners and process it into filtered/unfiltered datasets
|
|
- **Gamemaster API** - Access processed gamemaster data from any app on the site via REST API
|
|
- **Challonge Integration** - Manage tournaments with OAuth authentication
|
|
- **API Key Manager** - Securely store API keys in browser storage
|
|
|
|
## 🚀 Local Development
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20+
|
|
- npm or yarn
|
|
- Challonge API key (get from https://challonge.com/settings/developer)
|
|
|
|
### Environment Setup
|
|
|
|
1. **Copy environment template**:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. **Configure your API keys** in `.env`:
|
|
```bash
|
|
# Required: Get your API key from Challonge
|
|
VITE_CHALLONGE_API_KEY=your_actual_api_key_here
|
|
|
|
# Optional: Set default tournament for testing
|
|
VITE_DEFAULT_TOURNAMENT_ID=your_tournament_url
|
|
```
|
|
|
|
3. **Keep your `.env` file secure**:
|
|
- Never commit `.env` to git (already in `.gitignore`)
|
|
- Use `.env.example` for documentation
|
|
- Share API keys only through secure channels
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server (API key can be set via UI now!)
|
|
npm run dev
|
|
|
|
# Open browser to http://localhost:5173
|
|
```
|
|
|
|
**API Key Setup** (two options):
|
|
1. **Option 1: UI-based (Recommended)** - Use the API Key Manager tool at `/api-key-manager` to store your key locally in the browser
|
|
2. **Option 2: Environment-based** - Create `.env` file (see Environment Setup section below) for CI/CD or shared development
|
|
|
|
### Environment Setup (Optional)
|
|
|
|
If you prefer environment variables:
|
|
|
|
```bash
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your API keys
|
|
VITE_CHALLONGE_API_KEY=your_api_key_here
|
|
```
|
|
|
|
**Note**: The API Key Manager tool (`/api-key-manager`) allows you to store your key in browser localStorage, so `.env` configuration is now optional.
|
|
|
|
```bash
|
|
# Build the app
|
|
npm run build
|
|
|
|
# Preview production build
|
|
npm run preview
|
|
```
|
|
|
|
## 🐳 Docker Deployment
|
|
|
|
### Build and Run Locally
|
|
|
|
```bash
|
|
# Build the image
|
|
docker build -t pokedex-online .
|
|
|
|
# Run the container
|
|
docker run -d -p 8080:80 --name pokedex-online pokedex-online
|
|
|
|
# View in browser
|
|
open http://localhost:8080
|
|
```
|
|
|
|
### Using Docker Compose
|
|
|
|
```bash
|
|
# Start the service
|
|
docker-compose up -d
|
|
|
|
# Stop the service
|
|
docker-compose down
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
```
|
|
|
|
## 📦 Automated Deployment
|
|
|
|
Deploy to Synology NAS using the deployment script:
|
|
|
|
```bash
|
|
# Deploy to internal network (10.0.0.81)
|
|
npm run deploy:pokedex:internal
|
|
|
|
# Deploy to external network (home.gregrjacobs.com)
|
|
npm run deploy:pokedex:external
|
|
|
|
# Deploy with custom ports
|
|
npm run deploy:pokedex -- --target internal --port 8080 --ssl-port 8443
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
pokedex.online/
|
|
├── src/
|
|
│ ├── main.js # Application entry point
|
|
│ ├── App.vue # Root component with transitions
|
|
│ ├── style.css # Global styles
|
|
│ ├── router/
|
|
│ │ └── index.js # Vue Router configuration (4 routes)
|
|
│ ├── views/
|
|
│ │ ├── Home.vue # Landing page with tool cards
|
|
│ │ ├── ApiKeyManager.vue # API key storage and management
|
|
│ │ ├── GamemasterManager.vue # Gamemaster fetch/process/download
|
|
│ │ └── ChallongeTest.vue # API testing and validation
|
|
│ ├── components/
|
|
│ │ └── shared/
|
|
│ │ └── ProfessorPokeball.vue # Animated logo component
|
|
│ ├── services/
|
|
│ │ └── challonge.service.js # Challonge API client (20+ methods)
|
|
│ ├── utilities/
|
|
│ │ ├── constants.js # API config, types, CSV headers
|
|
│ │ ├── string-utils.js # String utilities
|
|
│ │ ├── csv-utils.js # CSV parsing and validation
|
|
│ │ ├── participant-utils.js # Participant management
|
|
│ │ ├── gamemaster-utils.js # Gamemaster processing
|
|
│ │ └── models/ # Data models (Tournament, Participant, Pokemon)
|
|
│ └── composables/
|
|
│ └── useChallongeApiKey.js # API key storage composable
|
|
├── .env.example # Environment template (optional)
|
|
├── index.html # HTML entry point
|
|
├── vite.config.js # Vite config with dev proxy
|
|
├── nginx.conf # Production nginx proxy config
|
|
├── package.json # Dependencies (Vue 3, Vue Router)
|
|
├── Dockerfile # Docker build (nginx:alpine)
|
|
├── docker-compose.yml # Docker Compose config
|
|
├── PROJECT_PLAN.md # Implementation roadmap
|
|
├── API_KEY_STORAGE.md # API key storage documentation
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🎯 Available Tools
|
|
|
|
### API Key Manager (`/api-key-manager`)
|
|
- Store your Challonge API key locally in browser localStorage
|
|
- Works across all devices and browsers (mobile, tablet, desktop)
|
|
- Masked display for security (shows "xxxx•••••••xxxx")
|
|
- Update or clear your key anytime
|
|
- No need to edit .env files
|
|
- Secure browser-native storage
|
|
|
|
### Gamemaster Manager (`/gamemaster`)
|
|
- Fetch latest Pokemon GO gamemaster from PokeMiners
|
|
- Process and break up into separate files
|
|
- Download pokemon.json, moves.json, and allFormsCostumes.json
|
|
- View statistics about downloaded data
|
|
|
|
### Challonge API Test (`/challonge-test`)
|
|
- Test your Challonge API connection
|
|
- Enter API key (or load from stored key)
|
|
- List your tournaments
|
|
- View tournament details and participants
|
|
- Verify API configuration is working
|
|
|
|
### Printing Tool (Coming Soon)
|
|
- Import RK9 player CSV files
|
|
- Generate team sheets
|
|
- Create player badges
|
|
- Print tournament materials
|
|
|
|
### Tournament Manager (Coming Soon)
|
|
- Manage Challonge tournaments
|
|
- Add/remove participants
|
|
- Submit match scores
|
|
- Track tournament progress
|
|
|
|
## 🔑 API Keys & Configuration
|
|
|
|
### Challonge API
|
|
1. Create account at https://challonge.com
|
|
2. Get API key from https://challonge.com/settings/developer
|
|
3. Add to `.env`:
|
|
```
|
|
VITE_CHALLONGE_API_KEY=your_key_here
|
|
```
|
|
|
|
### Environment Variables
|
|
All environment variables must be prefixed with `VITE_` to be available in the browser:
|
|
|
|
```bash
|
|
# ✅ Correct - Available in browser
|
|
VITE_CHALLONGE_API_KEY=abc123
|
|
|
|
# ❌ Wrong - Not accessible
|
|
CHALLONGE_API_KEY=abc123
|
|
```
|
|
|
|
Access in code:
|
|
```javascript
|
|
const apiKey = import.meta.env.VITE_CHALLONGE_API_KEY;
|
|
```
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
- **Vue 3.4** - Progressive JavaScript framework with Composition API
|
|
- **Vue Router 4** - Official routing library
|
|
- **Vite 5** - Next generation frontend tooling
|
|
- **Docker** - Containerization
|
|
- **nginx** - Web server for production
|
|
|
|
## 📚 Documentation
|
|
|
|
- [PROJECT_PLAN.md](./PROJECT_PLAN.md) - Complete implementation roadmap
|
|
- [GAMEMASTER_IMPLEMENTATION.md](./GAMEMASTER_IMPLEMENTATION.md) - Gamemaster feature details
|
|
- [Vue 3 Docs](https://vuejs.org/)
|
|
- [Challonge API](https://api.challonge.com/v1)
|
|
|
|
## 🔒 Security Notes
|
|
|
|
- **Never commit `.env`** - Contains sensitive API keys
|
|
- **Use environment variables** - All configs in `.env`
|
|
- **Prefix with VITE_** - Required for browser access
|
|
- **Keep API keys private** - Don't share in public repos
|
|
|
|
## 🔗 Related Apps
|
|
|
|
- **apps/** - Additional apps accessible at app.pokedex.online
|
|
|
|
## 📝 Development Notes
|
|
|
|
This project uses:
|
|
- Vue 3 Composition API with `<script setup>`
|
|
- Vite for fast HMR and optimized builds
|
|
- Multi-stage Docker builds for minimal image size
|
|
- nginx:alpine for production serving
|