204 lines
4.2 KiB
Markdown
204 lines
4.2 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get up and running with STUPA PDF API in 5 minutes!
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose installed
|
|
- Git installed
|
|
- 5 minutes of your time
|
|
|
|
## 🚀 Quick Setup
|
|
|
|
### 1. Clone and Navigate
|
|
|
|
```bash
|
|
git clone https://github.com/your-org/stupa-pdf-api.git
|
|
cd stupa-pdf-api
|
|
```
|
|
|
|
### 2. Generate Configuration
|
|
|
|
```bash
|
|
# Make the script executable
|
|
chmod +x scripts/create-env.sh
|
|
|
|
# Run the configuration script
|
|
./scripts/create-env.sh
|
|
```
|
|
|
|
Just press Enter to accept all defaults for a quick local setup.
|
|
|
|
### 3. Start Everything
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Wait about 30 seconds for all services to start.
|
|
|
|
### 4. Verify It's Working
|
|
|
|
```bash
|
|
# Check all services are running
|
|
docker compose ps
|
|
|
|
# Test the API
|
|
curl http://localhost:8000/
|
|
|
|
# Should return: {"message":"STUPA PDF API"}
|
|
```
|
|
|
|
## 🎯 Your First Application
|
|
|
|
### Using the Web Interface
|
|
|
|
1. **Open the Frontend**
|
|
- Navigate to http://localhost:3000
|
|
- You'll see the STUPA PDF application interface
|
|
|
|
2. **Upload a PDF Form**
|
|
- Click "Upload PDF" or drag and drop a PDF form
|
|
- The system will parse and extract data automatically
|
|
|
|
3. **Review Application Data**
|
|
- Check the extracted information
|
|
- Edit any fields if needed
|
|
- Add comparison offers for cost positions
|
|
|
|
4. **Save Your Work**
|
|
- Note the Application ID (e.g., "25-0001")
|
|
- Save the Application Key securely (shown once!)
|
|
|
|
### Using the API Directly
|
|
|
|
```bash
|
|
# Upload a PDF and create application
|
|
curl -X POST "http://localhost:8000/upload" \
|
|
-F "file=@your-form.pdf" \
|
|
-F "form_type=pa_form"
|
|
|
|
# Response includes:
|
|
# - pa_id: Your application ID
|
|
# - pa_key: Your access key (save this!)
|
|
```
|
|
|
|
## 📝 Common Tasks
|
|
|
|
### View Your Application
|
|
|
|
```bash
|
|
# Using the web interface
|
|
http://localhost:3000/applications/YOUR_PA_ID?key=YOUR_PA_KEY
|
|
|
|
# Using the API
|
|
curl "http://localhost:8000/applications/YOUR_PA_ID?format=json" \
|
|
-H "X-PA-KEY: YOUR_PA_KEY"
|
|
```
|
|
|
|
### Generate Filled PDF
|
|
|
|
```bash
|
|
# Download filled PDF
|
|
curl "http://localhost:8000/applications/YOUR_PA_ID?format=pdf" \
|
|
-H "X-PA-KEY: YOUR_PA_KEY" \
|
|
-o filled-form.pdf
|
|
```
|
|
|
|
### Add Attachments
|
|
|
|
```bash
|
|
# Upload an attachment
|
|
curl -X POST "http://localhost:8000/applications/YOUR_PA_ID/attachments" \
|
|
-H "X-PA-KEY: YOUR_PA_KEY" \
|
|
-F "file=@receipt.pdf"
|
|
```
|
|
|
|
### Manage Comparison Offers
|
|
|
|
Use the web interface to:
|
|
1. Click on any cost position
|
|
2. Add at least 3 comparison offers
|
|
3. Select your preferred offer
|
|
4. Save changes
|
|
|
|
## 🛠️ Quick Admin Tasks
|
|
|
|
### Access the Database
|
|
|
|
1. Open http://localhost:8080 (Adminer)
|
|
2. Login with:
|
|
- System: MySQL
|
|
- Server: `db`
|
|
- Username: `root`
|
|
- Password: (from your .env file)
|
|
- Database: `stupa`
|
|
|
|
### View API Documentation
|
|
|
|
- **Interactive Docs**: http://localhost:8000/docs
|
|
- **Alternative Docs**: http://localhost:8000/redoc
|
|
|
|
### Check Logs
|
|
|
|
```bash
|
|
# All services
|
|
docker compose logs -f
|
|
|
|
# Specific service
|
|
docker compose logs -f api
|
|
docker compose logs -f frontend
|
|
docker compose logs -f db
|
|
```
|
|
|
|
## 🔧 Quick Troubleshooting
|
|
|
|
### Services Won't Start
|
|
|
|
```bash
|
|
# Check for port conflicts
|
|
docker compose ps
|
|
|
|
# Restart everything
|
|
docker compose restart
|
|
|
|
# Full reset
|
|
docker compose down
|
|
docker compose up -d
|
|
```
|
|
|
|
### Can't Access Frontend
|
|
|
|
1. Check if port 3000 is already in use
|
|
2. Wait 30 seconds after starting services
|
|
3. Try http://127.0.0.1:3000 instead
|
|
|
|
### API Returns 429 (Too Many Requests)
|
|
|
|
The API has rate limiting. Default: 60 requests/minute per IP.
|
|
|
|
### Lost Application Key
|
|
|
|
Application keys cannot be recovered. You'll need to:
|
|
1. Use the master key (from .env) for admin access
|
|
2. Or create a new application
|
|
|
|
## 📚 Next Steps
|
|
|
|
Now that you're up and running:
|
|
|
|
1. **Explore the Frontend**: Try all features in the web interface
|
|
2. **Read API Docs**: Check http://localhost:8000/docs
|
|
3. **Customize Settings**: Edit `.env` for your needs
|
|
4. **Add Test Data**: Create sample applications
|
|
5. **Plan Deployment**: See [Deployment Guide](./DEPLOYMENT.md)
|
|
|
|
## 🆘 Getting Help
|
|
|
|
- Check [FAQ](./FAQ.md) for common questions
|
|
- See [Troubleshooting Guide](./TROUBLESHOOTING.md) for issues
|
|
- Review [API Reference](./API_REFERENCE.md) for integration
|
|
|
|
---
|
|
|
|
**Congratulations!** 🎉 You now have a working STUPA PDF API system! |