Deploying to Fly.io
Relevant source files
The following files were used as context for generating this wiki page:
Deploying the P4N Map application to Fly.io allows for a globally distributed, containerized deployment of the Next.js 16 application. The deployment leverages Fly.io's persistent volumes to maintain a durable cache of Park4Night spots, ensuring performance and stability across restarts and redeploys.
The application is configured to run in the cdg (Paris) region to maintain proximity to European data sources and services. It utilizes HTTP Basic Authentication to protect the instance once deployed, as it carries sensitive session information for the user's Park4Night+ account.
Sources: README.md:83-85, fly.toml:9-11
Deployment Workflow
The deployment process follows a standard containerized workflow where the application is built via a Dockerfile and managed through the Fly CLI.
Initialization and Launch
To start a new deployment, users must initialize the application without an immediate deploy to allow for configuration of secrets and volumes. This is achieved using the fly launch --no-deploy command or by manually creating an app with fly apps create <name>.
Sources: README.md:92-93, fly.toml:3-4
The diagram shows the logical progression from initial launch to a live application.
Sources: README.md:92-99, fly.toml:3-7
Configuration and Infrastructure
The deployment is defined by the fly.toml configuration file, which specifies the compute resources, environment variables, and mounting points for persistent storage.
Hardware and Scaling
The application is configured to run on minimal hardware suitable for personal use, utilizing a shared-cpu-1x VM with 512MB of RAM. It includes an auto-stop feature to minimize costs by scaling to zero when the application is idle.
Sources: fly.toml:23-30
Persistent Storage (Volumes)
A critical component of the deployment is the p4n_cache volume. This durable volume is used to store effectively-static upstream data from Park4Night, preventing unnecessary re-queries and surviving redeploys.
| Volume Attribute | Value | Description |
|---|---|---|
| Name | p4n_cache | The internal identifier for the volume |
| Size | 1GB | Minimum recommended size for spot caching |
| Region | cdg | Must match the primary app region |
| Mount Point | /data | Maps to P4N_CACHE_DIR in the app |
Sources: fly.toml:13-21, src/lib/cache.ts:16-18
Environment Variables and Secrets
Fly.io handles both public configuration and sensitive credentials through environment variables and encrypted secrets.
| Variable | Type | Description |
|---|---|---|
PORT | Env | Internal application port (default 8080) |
GEMINI_MODEL | Env | Defaults to gemini-2.5-flash |
P4N_CACHE_DIR | Env | Set to /data to point to the mounted volume |
PARK4NIGHT_SESSION | Secret | The PHPSESSID cookie value for P4N+ |
GEMINI_API_KEY | Secret | Google AI Studio key for voice assistant |
APP_GATE_USER | Secret | Username for HTTP Basic Auth |
APP_GATE_SECRET | Secret | Password for HTTP Basic Auth |
Sources: README.md:94-98, fly.toml:13-17
Data Persistence Architecture
The application uses a hybrid memory/disk cache strategy to handle Park4Night data. On Fly.io, the src/lib/cache.ts module looks for the P4N_CACHE_DIR environment variable to determine where to persist the p4n-cache.json file.
This diagram illustrates how the cache module interacts with the Fly.io persistent volume to ensure data survives restarts.
Sources: src/lib/cache.ts:1-25, fly.toml:19-21
Deployment Execution
The final step is executing the deployment, which builds the Docker container and pushes it to Fly.io's infrastructure.
# Set required secrets before deployment
fly secrets set \
PARK4NIGHT_SESSION="<phpsessid>" \
GEMINI_API_KEY="<key>" \
APP_GATE_USER="me" \
APP_GATE_SECRET="<password>"
# Execute deploy
fly deploy
Sources: README.md:94-99
The deployment relies on the package.json build scripts, specifically next build, and the Node.js 22 runtime as specified in the engines configuration.
Sources: package.json:7, 30
Security and Networking
The application is configured to force HTTPS and uses an internal port of 8080. The APP_GATE_SECRET is used to activate an HTTP Basic Gate, ensuring the deployed instance is private and secure.
Sources: README.md:100-102, fly.toml:23-26
Conclusion
Deploying to Fly.io provides a robust environment for P4N Map. By combining fly.toml configuration, persistent volumes for caching, and secret management for secure authentication, the application remains performant and private. The configuration ensures that the Park4Night session is protected while maintaining a fast user experience through durable data persistence.