170 lines
3.5 KiB
Markdown
170 lines
3.5 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get the A2P AutoPilot API server running in 5 minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+ installed
|
|
- PostgreSQL running locally or accessible remotely
|
|
- Redis running (for BullMQ workers)
|
|
|
|
## Step 1: Install Dependencies
|
|
|
|
```bash
|
|
cd /Users/jakeshore/.clawdbot/workspace/a2p-autopilot
|
|
npm install
|
|
```
|
|
|
|
## Step 2: Create Database
|
|
|
|
```bash
|
|
# Create PostgreSQL database
|
|
createdb a2p_autopilot
|
|
|
|
# Or using psql
|
|
psql -c "CREATE DATABASE a2p_autopilot;"
|
|
```
|
|
|
|
## Step 3: Configure Environment
|
|
|
|
```bash
|
|
# Copy example environment file
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your credentials
|
|
nano .env
|
|
```
|
|
|
|
**Required variables:**
|
|
```env
|
|
DATABASE_URL=postgresql://localhost:5432/a2p_autopilot
|
|
REDIS_URL=redis://localhost:6379
|
|
API_KEY=your-secret-api-key-here
|
|
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
TWILIO_AUTH_TOKEN=your-twilio-auth-token
|
|
```
|
|
|
|
## Step 4: Run Migrations
|
|
|
|
```bash
|
|
# Generate migration files from schema
|
|
npm run db:generate
|
|
|
|
# Apply migrations to database
|
|
npm run db:migrate
|
|
```
|
|
|
|
## Step 5: Start Server
|
|
|
|
```bash
|
|
# Development mode (with hot reload)
|
|
npm run dev
|
|
|
|
# Or production mode
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
Server will start on `http://localhost:3000`
|
|
|
|
## Step 6: Test the API
|
|
|
|
### Health Check
|
|
```bash
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
### Create a Submission
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/submissions \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer your-secret-api-key-here" \
|
|
-d @test-submission.json
|
|
```
|
|
|
|
### Get Stats
|
|
```bash
|
|
curl http://localhost:3000/api/stats \
|
|
-H "Authorization: Bearer your-secret-api-key-here"
|
|
```
|
|
|
|
### List Submissions
|
|
```bash
|
|
curl "http://localhost:3000/api/submissions?status=pending&limit=10" \
|
|
-H "Authorization: Bearer your-secret-api-key-here"
|
|
```
|
|
|
|
## Optional: Drizzle Studio (Database GUI)
|
|
|
|
```bash
|
|
npm run db:studio
|
|
```
|
|
|
|
Opens a web-based database GUI at `https://local.drizzle.studio`
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Connection Error
|
|
- Verify PostgreSQL is running: `pg_isready`
|
|
- Check DATABASE_URL in .env is correct
|
|
- Ensure database exists: `psql -l | grep a2p_autopilot`
|
|
|
|
### Redis Connection Error
|
|
- Verify Redis is running: `redis-cli ping`
|
|
- Should return "PONG"
|
|
- Check REDIS_URL in .env
|
|
|
|
### Port Already in Use
|
|
- Change PORT in .env
|
|
- Or kill process: `lsof -ti:3000 | xargs kill`
|
|
|
|
### Migration Errors
|
|
- Delete drizzle/ folder and regenerate: `rm -rf drizzle && npm run db:generate`
|
|
- Drop and recreate database if needed
|
|
|
|
## Next Steps
|
|
|
|
1. **Review API Documentation** — See README.md for all endpoints
|
|
2. **Integrate Landing Pages** — Connect the pages/ module
|
|
3. **Wire Up Submission Engine** — Connect the engine/ module
|
|
4. **Enable Polling** — Start BullMQ workers for status updates
|
|
5. **Test Webhooks** — Use ngrok to test Twilio webhooks locally
|
|
|
|
## Development Tips
|
|
|
|
### Watch Database Changes
|
|
```bash
|
|
# Terminal 1: Run server
|
|
npm run dev
|
|
|
|
# Terminal 2: Watch database
|
|
npm run db:studio
|
|
```
|
|
|
|
### Check Logs
|
|
Logs are pretty-printed in development with colors and timestamps.
|
|
|
|
### Type Checking
|
|
```bash
|
|
npm run typecheck
|
|
```
|
|
|
|
### Database Reset (DANGER!)
|
|
```bash
|
|
# Drop all tables and re-migrate
|
|
psql a2p_autopilot -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
|
|
npm run db:migrate
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
See README.md for production deployment checklist including:
|
|
- Environment variable security
|
|
- Database connection pooling
|
|
- Redis clustering
|
|
- Process management (PM2/systemd)
|
|
- Reverse proxy (nginx)
|
|
- SSL/TLS configuration
|
|
- Log aggregation
|
|
- Monitoring and alerting
|