================================================================================
                    PRIMEIRA LIGA STATS - DOCKER DEPLOYMENT
================================================================================

Project Name: Primeira Liga Stats
Version: 1.0.0
Created: February 2026
Framework: Next.js 14 with TypeScript
Database: PostgreSQL 15 (Self-hosted via Docker)

================================================================================
                           QUICK START
================================================================================

To deploy the entire application, simply run:

    docker compose up -d

That's it! The application will be available at:

    Main Website:  http://localhost:3000
    Admin Panel:   http://localhost:3000/admin

================================================================================
                         WHAT HAPPENS
================================================================================

When you run `docker compose up -d`, Docker will:

1. Create a PostgreSQL 15 database container
2. Initialize the database with all required tables
3. Pre-configure the API key and default settings
4. Build the Next.js application
5. Start the web server on port 3000

No manual configuration is required!

================================================================================
                              FEATURES
================================================================================

MAIN WEBSITE (/):
- Live match scores with real-time updates
- League standings table with team positions
- Top scorers leaderboard
- Recent match results
- Upcoming fixtures schedule
- Auto-refresh countdown timer (5 minutes default)
- Portuguese national colors theme (red/green)

ADMIN PANEL (/admin):
- Layout Settings (colors, site name, sections visibility)
- API Key Management (view/change API key)
- League Switcher (Primeira Liga / UEFA Euro)
- API Statistics (request tracking, charts)

================================================================================
                           DOCKER COMMANDS
================================================================================

Start the application:
    docker compose up -d

Stop the application:
    docker compose down

View logs:
    docker compose logs -f

View app logs only:
    docker compose logs -f app

View database logs only:
    docker compose logs -f db

Rebuild after changes:
    docker compose up -d --build

Remove everything (including data):
    docker compose down -v

================================================================================
                           CONFIGURATION
================================================================================

The following environment variables are pre-configured in docker-compose.yml:

    DATABASE_URL         - PostgreSQL connection string
    API_FOOTBALL_API_KEY - Your API-Football API key
    NEXTAUTH_URL         - Application URL
    NEXTAUTH_SECRET      - Session encryption key

To change the API key:
1. Edit docker-compose.yml and update API_FOOTBALL_API_KEY
2. Run: docker compose up -d

Or use the Admin Panel at /admin to change it without restarting.

================================================================================
                            DATA PERSISTENCE
================================================================================

Database data is stored in a Docker volume named 'postgres_data'.
This means your data persists even when containers are stopped or removed.

To backup the database:
    docker exec primeira_liga_db pg_dump -U primeiraliga primeiraliga > backup.sql

To restore from backup:
    docker exec -i primeira_liga_db psql -U primeiraliga primeiraliga < backup.sql

================================================================================
                         PORT CONFIGURATION
================================================================================

Default port: 3000

To change the port, edit docker-compose.yml:

    ports:
      - "8080:3000"    # Change 8080 to your desired port

================================================================================
                              SERVICES
================================================================================

The docker-compose setup includes two services:

1. db (PostgreSQL 15)
   - Container name: primeira_liga_db
   - Internal port: 5432
   - Database: primeiraliga
   - User: primeiraliga
   - Password: primeiraliga2024

2. app (Next.js Application)
   - Container name: primeira_liga_app
   - External port: 3000
   - Auto-restarts on failure

================================================================================
                            TROUBLESHOOTING
================================================================================

PROBLEM: Container won't start
SOLUTION: Check logs with `docker compose logs -f`

PROBLEM: Database connection failed
SOLUTION: Wait a few seconds for the database to initialize, then try again

PROBLEM: Port 3000 already in use
SOLUTION: Change the port in docker-compose.yml or stop the conflicting service

PROBLEM: API data not loading
SOLUTION: 
1. Check API key is valid at api-football.com
2. Check daily API limits (free tier: 100 requests/day)
3. View logs: docker compose logs -f app

PROBLEM: Changes not appearing after edit
SOLUTION: Rebuild with `docker compose up -d --build`

================================================================================
                           SYSTEM REQUIREMENTS
================================================================================

- Docker Engine 20.10+
- Docker Compose 2.0+
- 1GB RAM minimum
- 2GB disk space

================================================================================
                         ACCESSING THE DATABASE
================================================================================

Connect to PostgreSQL directly:
    docker exec -it primeira_liga_db psql -U primeiraliga -d primeiraliga

Useful SQL commands:
    \dt                          -- List all tables
    SELECT * FROM "Settings";    -- View settings
    SELECT * FROM "ApiRequestLog" ORDER BY "createdAt" DESC LIMIT 10;

================================================================================
                              API LIMITS
================================================================================

API-Football Free Tier:
- 100 requests per day
- Data updates every 15 minutes

The application refreshes every 5 minutes by default.
You can increase this interval in the Admin Panel to conserve API calls.

================================================================================
                              SUPPORT
================================================================================

API-Football: https://www.api-football.com/documentation-v3
Docker: https://docs.docker.com/
Next.js: https://nextjs.org/docs

================================================================================