Local Setup & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
P4N Map is a private web application designed to enhance the Park4Night+ experience by providing a custom UI for multi-stop trip planning (A → B → C). It functions as a server-side proxy for Park4Night data, allowing users to filter spots within a specific corridor of their route and synchronize their findings with their official account.
Sources: README.md:1-10
This guide outlines the technical requirements, environment configuration, and authentication workflows necessary to run the application in a local development environment or a private production instance.
Technical Stack & Requirements
The project is built using modern web technologies and requires specific runtime versions for local execution.
| Technology | Requirement |
|---|---|
| Node.js | version >= 22 |
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| UI Library | React 19 |
| Styling | Tailwind CSS 4.1.0 |
| Browser Automation | Playwright (for authentication) |
Sources: package.json:2-31, README.md:21-28
Installation and Quick Start
To set up the project locally, follow these steps:
- Clone and Configure: Copy the example environment file and install dependencies.
cp .env.example .env.local npm install - Launch Development Server:
npm run dev - Access Application: Open
http://localhost:3000. The Settings page (/settings) is used to verify session validity and configure user preferences.
Sources: README.md:30-36, src/app/settings/page.tsx:78-83
Environment Configuration
The application relies on several environment variables to handle external API integrations and security gates.
| Variable | Requirement | Purpose |
|---|---|---|
PARK4NIGHT_SESSION | Optional | Park4Night's PHPSESSID cookie value. Can be injected via .env.local or Fly secrets to bypass the login form. |
GEMINI_API_KEY | Required (Voice) | Google AI Studio key used for the voice assistant feature. |
GEMINI_MODEL | Optional | Defaults to gemini-flash-latest. |
APP_GATE_USER | Optional | Username for HTTP Basic auth gate. |
APP_GATE_SECRET | Optional | Password for HTTP Basic auth. If empty, the gate is off (default for local dev). |
P4N_CACHE_DIR | Optional | Directory for persistent JSON cache. Defaults to ./.p4n-cache. |
Sources: README.md:46-52, src/lib/cache.ts:32-37
Authentication Flow
P4N Map uses a browser-based authentication strategy to handle Park4Night's reCAPTCHA implementation.
Browser Automation Login
Because the official Park4Night login uses Google reCAPTCHA Enterprise, invisible logins often fail as bots. P4N Map uses Playwright to drive a headed browser (locally) or a server-side session.
The application includes a specialized DIDOMI_KILLSWITCH to neutralize consent banners that might interfere with automated interactions.
Sources: src/lib/p4n-login.ts:16-105, src/app/settings/page.tsx:114-123
Manual Session Injection
Alternatively, users can manually extract their PHPSESSID from their browser's developer tools after logging into the official Park4Night website and paste it into the .env.local file.
Sources: README.md:33-44
Data Persistence & Caching
The application implements a durable, refresh-only cache to minimize redundant requests to Park4Night's private endpoints.
- Storage: Entries are stored in memory and mirrored to a JSON file (default
p4n-cache.json). - Persistence: On platforms like Fly.io,
P4N_CACHE_DIRshould point to a mounted volume to survive redeploys. - Expiry: There is no automatic TTL; entries are only replaced on explicit user-triggered refreshes.
Sources: src/lib/cache.ts:1-20, README.md:27-28
Deployment (Fly.io)
For private production use, the application is optimized for deployment on Fly.io using HTTP Basic authentication for security.
# Set secrets before deployment
fly secrets set \
PARK4NIGHT_SESSION="<phpsessid>" \
GEMINI_API_KEY="<key>" \
APP_GATE_USER="me" \
APP_GATE_SECRET="<random_password>"
fly deploy
Sources: README.md:65-72
Summary
Setting up P4N Map involves preparing a Node.js 22 environment, configuring environment variables for session management and AI features, and completing the authentication handshake with Park4Night. Local development utilizes a headed browser for reCAPTCHA compatibility, while production deployments rely on secret injection and HTTP basic gates to maintain privacy.