5-Minute Integration

Get Corgi up and running in under 5 minutes with this streamlined guide. No complex configuration, no dependency headaches—just clone, run, and verify.

Prerequisites

You only need two tools installed:

Quick Check

# Verify you have Docker and Git
docker --version
git --version

Docker (with Docker Compose)
Git

That's it! No Python setup, no database installation, no environment configuration.

Step 1: Clone and Setup

Terminal
# Clone the repository
git clone https://github.com/AndrewNordstrom/corgi-recommender-service.git
cd corgi-recommender-service

# The setup script will handle environment configuration automatically

Auto-Configuration

The setup script automatically creates your .env file from the example template—no manual configuration needed!

Step 2: Start the Full Stack

Terminal

# Start everything in demo mode (includes frontend + API + database)
./run-dev.sh demo

This single command: - Creates the environment configuration - Builds all Docker containers - Starts PostgreSQL database - Starts Redis cache - Starts Corgi API service - Starts ELK client frontend - Runs health checks on all services

What's Starting

ELK Client Frontend: http://localhost:5314
Corgi API: http://localhost:5002
Database: PostgreSQL on port 5432
Cache: Redis on port 6379

Step 3: Verify It's Working

Quick Health Check

Terminal

# Check that all services are running
./run-dev.sh status

Frontend Verification

Open http://localhost:5314 in your browser. You should see the ELK client interface.

API Verification

Terminal

# Test the API health endpoint
curl http://localhost:5002/health

Expected Response

{
  "status": "healthy",
  "timestamp": "2025-01-XX...",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

Step 4: Your First API Call

Make your first recommendation request:

Terminal

# Get recommendations for a sample user
curl -X POST http://localhost:5002/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "demo_user",
    "limit": 5
  }'

Try the Interactive Frontend

Instead of curl, you can use the ELK client at http://localhost:5314 to interact with recommendations through a beautiful web interface.

Success

You now have a fully functional Corgi recommendation system running locally with:

Smart Recommendations: AI-powered content discovery
Privacy-First: No data collection or tracking
Fediverse Integration: Ready to connect with Mastodon and other ActivityPub services
Real-time Updates: Live recommendation updates
Modern UI: Clean, responsive web interface

Next Steps

Ready to Integrate?

API Documentation: http://localhost:5002/docs - Interactive API explorer
Integration Guide: Learn how to connect your Mastodon instance → ELK Integration
Architecture Deep Dive: Understand how it works → Architecture

Troubleshooting

Port Conflicts

If you see "port already in use" errors:

# Stop any existing services
./run-dev.sh stop

# Start fresh
./run-dev.sh demo

Docker Issues

# Clean up Docker resources
docker system prune -f

# Restart Docker Desktop (if on macOS/Windows)
# Then try again
./run-dev.sh demo

Need Help?

# View detailed logs
./run-dev.sh logs

# View logs for specific service
./run-dev.sh logs corgi-api

Still having issues?

Check out our troubleshooting guide or open an issue.

Total time: Under 5 minutes
What you have: A complete, production-ready recommendation system
What's next: Integrate with your Fediverse instance and start getting smart recommendations