Travel Map Application

A Laravel application with React/Inertia.js frontend for managing travel maps.

🌐 Deployments

This project uses separate DEV and PROD environments:

• DEV: https://dev.travelmap.koller.dk/ - Automatically deployed on every merge to main
• PROD: https://travelmap.koller.dk/ - Manually deployed via GitHub Actions

See GitHub Environments Setup Guide for configuration instructions.

Development Workflow

This project follows the GitHub Flow branching strategy for a streamlined development and deployment process.

📖 Documentation

• GitHub Environments Setup Guide - Complete DEV/PROD setup guide ⭐
• Deployment Setup - Complete deployment guide for all-inkl.com
• Branching Strategy Guide - Complete guide to GitHub Flow workflow
• Contributing Guide - How to contribute to this project
• Pipeline Overview - Detailed CI/CD pipeline documentation
• GitHub Secrets Configuration - Configure environment variables via GitHub Secrets (legacy)
• Secrets Quick Start - Quick reference for setting up GitHub Secrets (legacy)
• Secrets Workflow Diagram - Visual guide to how secrets are deployed
• Workflow Checklist - Step-by-step checklist for development workflow
• GitHub Actions - Detailed CI/CD pipeline documentation
• Workflow Diagrams - Visual workflow diagrams
• Quick Reference - Common commands and troubleshooting
• Mapbox Geocoder Feature - Location search functionality documentation
• Mapbox Migration Guide - Migration from Leaflet to Mapbox GL JS
• Trip Collaboration - Multi-user trip collaboration feature documentation

🚀 Quick Start

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and test
vendor/bin/pint && npm run format && composer test

# Push and create PR
git push origin feature/your-feature-name

🤖 GitHub Copilot Integration

This repository is configured with a custom environment for GitHub Copilot to automatically set up the development environment when working on issues. The configuration is defined in .github/copilot-environment.yml and includes:

• PHP 8.4 with Composer
• Node.js 22 with npm
• Automatic installation of dependencies
• Laravel environment setup (.env file, application key)
• Database migrations
• Frontend asset building

When GitHub Copilot starts working on an issue, it will automatically:

1. Install PHP and Node.js dependencies
2. Configure the Laravel environment
3. Run database migrations
4. Build frontend assets

For detailed instructions and project conventions, see .github/copilot-instructions.md.

Features & Technology

• Icons: FontAwesome
• Map Library: Mapbox GL JS (migrated from Leaflet)
• Location Search: Mapbox Geocoder
• Frontend: React 19 with TypeScript and Inertia.js
• Backend: Laravel 12 with PHP 8.2+

Requirements

• PHP 8.1 or higher
• Composer
• Node.js 18 or higher
• npm or yarn
• MySQL or PostgreSQL database

Installation & Setup

1. Install PHP Dependencies

composer install

2. Install JavaScript Dependencies

npm install

3. Configure Environment

Copy the example environment file and configure your database:

cp .env.example .env

Edit .env and set your database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

4. Generate Application Key

php artisan key:generate

5. Run Database Migrations

php artisan migrate

6. Configure External Services (Optional)

Mapbox (Required for map functionality)

Get your Mapbox access token from Mapbox Account:

MAPBOX_ACCESS_TOKEN=your_mapbox_token_here

Unsplash (Optional - for on-demand trip and marker images)

Get your Unsplash access key from Unsplash Developers:

UNSPLASH_ACCESS_KEY=your_unsplash_access_key_here
UNSPLASH_UTM_SOURCE="${APP_NAME}"

Features:

• On-demand image fetching for trips and markers (click placeholder to load)
• Uses official Unsplash PHP wrapper for proper API compliance
• Images are cached for 30 days to minimize API calls
• Properly tracks downloads to increment photo views
• Hotlinks images directly from Unsplash (as per API guidelines)
• Rate Limit: 50 requests/hour (free tier)
• Falls back to placeholder images if API is unavailable

Usage:

1. Click on the image placeholder icon for any trip or marker
2. The application fetches a relevant image from Unsplash
3. Image is displayed and cached for future use
4. Photo views are tracked to benefit photographers

Note: If you don't configure an Unsplash API key, the application will display clickable placeholder images. Configure the UNSPLASH_UTM_SOURCE to attribute traffic to your application (defaults to APP_NAME).

Le Chat Agent (Optional - for AI-powered marker enrichment)

Get your API key from Mistral AI Console:

LECHAT_API_KEY=your_lechat_api_key_here
LECHAT_MARKER_ENRICHMENT_AGENT_ID=your_agent_id_here
LECHAT_TRAVEL_RECOMMENDATION_AGENT_ID=your_agent_id_here

7. Build Frontend Assets

For development:

npm run dev

For production:

npm run build

Running the Application

Development Mode

1. Start the Laravel development server (in one terminal):

   php artisan serve

2. Start the Vite development server (in another terminal):

   npm run dev

3. Open your browser and visit:

   http://localhost:8000
   

Production Mode

1. Build the frontend assets:

   npm run build

2. Configure your web server (Apache/Nginx) to point to the public directory

3. Ensure proper file permissions:

   chmod -R 775 storage bootstrap/cache

Testing

Unit and Feature Tests

Run the PHP test suite:

php artisan test

Or using Pest directly:

./vendor/bin/pest

Contributing

We welcome contributions! Please read our Contributing Guide for details on:

• Setting up your development environment
• Our code of conduct
• The pull request process
• Coding standards

Additional Commands

Clear Application Cache

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Create Database Seeder Data

php artisan db:seed

Troubleshooting

• Port 8000 already in use: Specify a different port with php artisan serve --port=8001
• Database connection errors: Verify your .env database credentials
• Permission errors: Ensure storage and bootstrap/cache directories are writable
• Frontend not loading: Make sure npm run dev is running alongside php artisan serve