]
Kayak Map is an interactive web application designed to help users explore and discover kayak trails in various regions. Built using Vue.js (v3), Vuetify, and Laravel (v11), the application offers a dynamic map interface, detailed trail information, and a seamless user experience for outdoor enthusiasts. It integrates geolocation services, trail visualization, and region-based searching, leveraging OpenStreetMap and Overpass API for geographical data.
We are working with a dataset of nearly 200 river trails across Poland. These are carefully prepared and verified routes. Our goal is to process GPX (GPS Exchange Format) files, allowing us to modify or add new trails based on this data. Additionally, we aim to enhance the experience by adding key informational or warning points along the trails to inform or alert users about hazardous conditions or helpful locations.
Our main objectives include:
- Gathering comprehensive data on Polish kayak trails and making it freely available to kayaking enthusiasts in Poland.
- Providing users with safe and informed experiences while exploring the beautiful landscapes of our rivers.
- Processing GPX trails for both modifying existing routes and adding new ones to our growing database.
- Adding critical points to warn users about obstacles, hazards, or other significant markers along their kayaking journey.
- Developing future integration with devices to enhance the kayaking experience, such as GPS trackers or water-level monitoring devices.
This project aspires to become the most comprehensive and user-friendly resource for exploring Polish rivers by kayak, providing detailed routes and information for outdoor enthusiasts.
The main objectives and key aspects of this application are:
- 🧭 Interactive Map: Provide users with a dynamic and interactive map experience.
- 🗺️ Region-Based Search: Enable filtering by country, state, city, and geographic regions.
- 📐 Geospatial Data: Store and process trails using geospatial data types in the database.
- 🔍 Search Optimization: Implement URL-based routing and filters to enhance SEO performance.
- 📑 Trail Information: Present users with detailed information on each trail, including its difficulty, scenery, and region.
- 📡 API Integration: Use OpenStreetMap, Overpass API, and Nominatim for real-time geospatial data and geocoding.
- 📈 Performance: Ensure efficient data handling through asynchronous job queues for large datasets and trail imports.
- 📱 Mobile-First Design: Implement a responsive design using Vuetify for a seamless experience across devices.
- ✅ Fully interactive map with leaflet integration.
- ✅ SEO-friendly URL routing for each trail and region.
- ✅ Real-time GPS location tracking.
- ✅ Integration with OpenStreetMap and Overpass API for real-time data.
- ✅ Detailed trail information, including start and end points, length, and difficulty.
- ✅ Modular Vue.js architecture with Vuex for state management.
- ✅ Geospatial data types for storing trail routes and geographic boundaries in the database.
- Frontend: Vue.js (v3), Vuetify, Vuex, Leaflet.js, @vue-leaflet/vue-leaflet
- Backend: Laravel (v11), MySQL with spatial extensions
- APIs:
- OpenStreetMap/Overpass API: For fetching rivers and geographic features.
- Nominatim: For geocoding and reverse geocoding locations.
- Database: MySQL with support for geographic data types (
GEOMETRY,GEOGRAPHY). - Job Queue: Asynchronous task handling for processing large datasets like trail imports and region mapping.
- Docker Desktop - pobierz tutaj
- Node.js (v16+) - pobierz tutaj
- Git - pobierz tutaj
# 1. Klonuj projekt
git clone https://github.com/yourusername/kayak-map.git
cd kayak-map
# 2. Automatyczny setup (wszystko się skonfiguruje)
npm run setup
# 3. Gotowe! 🎉Po setup aplikacja dostępna pod:
- Frontend: http://localhost:5173 (development)
- Backend: http://localhost:8000
- PhpMyAdmin: http://localhost:8081 (baza danych)
Setup automatycznie:
- ✅ Uruchamia MariaDB w kontenerze Docker
- ✅ Tworzy wszystkie tabele (migrate:fresh)
- ✅ Importuje dane produkcyjne z backup (164 szlaki, 232 regiony, 5206 punktów)
- ✅ Konfiguruje PhpMyAdmin do zarządzania bazą
- ✅ Tworzy storage symlink (
public/storage→storage/app/public)
Dane po instalacji:
# Sprawdź status projektu i bazy
make status
# Sprawdź dane w bazie
docker exec mariadb mariadb -u root -padmin123 kayak_map -e "
SELECT COUNT(*) as trails FROM trails;
SELECT COUNT(*) as regions FROM regions;"
# Sprawdź czy storage symlink działa
ls -la public/storage # Powinien wskazywać na ../storage/app/publicNie martw się! Wszystko działa przez Docker - nie musisz instalować PHP ani Composer lokalnie:
# Wszystkie komendy przez helper script:
./dev-helper.sh composer install # Composer w kontenerze
./dev-helper.sh artisan make:model Post # Laravel commands
./dev-helper.sh migrate # Migracje
./dev-helper.sh tinker # Laravel Tinker
./dev-helper.sh help # Zobacz wszystkie dostępne komendy# Development
npm run dev # Frontend hot-reload
./dev-helper.sh artisan serve # Backend server (w kontenerze)
# Zarządzanie bazą danych
npm run db:backup # Backup bazy danych
npm run db:restore # Przywróć z backup
./dev-helper.sh db-fresh # Świeże migracje + dane testowe
# Docker
docker-compose up -d # Uruchom kontenery
docker-compose down # Zatrzymaj kontenery
docker-compose logs -f # Zobacz logi
# Problemy? Reset wszystkiego:
npm run fresh # Świeża instalacja (czyści kontenery + volumny)
npm run fresh:deep # + usuwa node_modules i vendor| Problem | Rozwiązanie |
|---|---|
| Docker nie odpowiada? | docker-compose down -v && npm run fresh |
| Błędy z bazą danych? | npm run db:restore (przywróć dane z backup) |
| Problemy z cache? | ./dev-helper.sh artisan cache:clear |
| Chcesz zacząć od zera? | npm run fresh:deep (usuwa wszystko) |
| Brakuje Composer/PHP? | Używaj ./dev-helper.sh - wszystko działa w kontenerze |
kayak-map/
├── 🗄️ Baza danych → MariaDB (port 3306) z danymi produkcyjnymi
├── 🐳 Docker → Wszystkie serwisy (nginx, php, redis, mariadb)
├── 🎨 Frontend → Vue.js + Vuetify (port 5173)
├── ⚙️ Backend → Laravel 11 (port 8000)
├── 📊 PhpMyAdmin → Zarządzanie bazą (port 8081)
└── 🛠️ Dev Tools → dev-helper.sh dla wygody
- Zainstaluj plugin Dev Containers w PhpStorm
- Otwórz projekt → kliknij "Reopen in Container"
- Poczekaj 2 minuty na automatyczny setup
- Gotowe! - pełne środowisko z debuggerem
- 🐛 Xdebug skonfigurowany dla PhpStorm (breakpoints działają!)
- 🗄️ Database connection w PhpStorm Database tool
- 🔧 PHP Interpreter skonfigurowany (Docker PHP 8.3)
- 🚀 Hot reload dla frontend (Vite) i backend
- 📦 Wszystkie dependencje zainstalowane automatycznie
- 🌐 Port forwarding - wszystkie serwisy dostępne lokalnie
- ⚡ Launch configurations - gotowe konfiguracje debug/artisan/npm w
.devcontainer/phpstorm-launch.xml
- Developer PHP → pełne debugging + database tools
- Developer Kotlin → nie musi znać PHP, wszystko gotowe w PhpStorm
- Identyczne środowisko na każdej maszynie
- Zero "works on my machine" problems
Szczegóły: Zobacz .devcontainer/README.md
Kliknij tutaj jeśli chcesz tradycyjną instalację z lokalnym PHP
- Node.js >= 14.x
- Composer >= 2.x
- PHP >= 8.x
- MySQL with spatial extensions enabled
git clone https://github.com/yourusername/kayak-map.git
cd kayak-map-
Install backend dependencies:
composer install
-
Set up environment variables:
cp .env.local.example .env.local
-
Generate application key:
php artisan key:generate
-
Run database migrations:
php artisan migrate
-
Seed the database:
php artisan db:seed
-
Start the Laravel development server:
php artisan serve
-
Install frontend dependencies:
npm install
-
Start the frontend development server:
npm run dev
The application provides a series of API endpoints to manage and fetch trails, regions, and geographic data.
- GET /api/v1/trails: Fetch trails based on bounding box and filters (difficulty, scenery, etc.).
- GET /api/v1/regions: Retrieve regions such as countries, states, cities.
- POST /api/v1/geocode: Geocode addresses and locations.
For detailed API documentation, refer to the routes/api.php file and the built-in Laravel API Resource Collections used in the project.
The application follows a modular structure with separate modules for managing trails, maps, and regions. Each module is organized under the src/modules/ directory with a dedicated state, actions, and components.
- MapView.vue: Main map interface to explore and interact with trails.
- TrailPopup.vue: Displays detailed information about a selected trail.
- RiverTrack.vue: Displays the river's path and trail route.
- SidebarTrails.vue: Sidebar filter and trail list view.
- GeocodingService: Handles geolocation and region-based trail lookups.
- TrailSeeder: Seeds the database with trails and connects them to geographic regions.
Vuex is used for state management, where we handle:
- Trails: Fetch, filter, and manage kayak trails.
- Regions: Geographic region hierarchy and filtering.
- User Preferences: Customizable UI and map preferences.
The project leverages spatial extensions in MySQL to store and query geographic data. Each trail is associated with regions, and its route is stored in the form of spatial data points.
Regions (Country/State/City/Geographic Area) are stored in a hierarchical structure, allowing trails to belong to multiple regions. Slugs are generated for SEO-friendly URLs like /poland/dolnoslaskie/wroclaw.
We welcome contributions! Please follow the guidelines below:
- Fork the repository.
- Create a new branch (
feature/your-feature). - Commit your changes.
- Open a pull request with a detailed description.
This project is open-source and available under the MIT License.