Deployment Environments

Volpe builds for two hosts: Farfalla (web, via Cloudflare Pages) and Fenice (apps, via GitLab Package Registry). Each host has its own set of environments.

Web (Farfalla)

Deployed to Cloudflare Pages. Each environment maps to a separate Pages project.

Environment	URL	Cloudflare Project	Branch	Trigger
Production	volpe.publica.la	volpe	main	Manual (from main)
Staging	staging.volpe.publica.la	volpe	dev	Auto (on dev push)
Volpe2	nextgen.volpe.publica.la	volpe2	main	Manual (from main)
Prototype	prototype.volpe.publica.la	volpe-prototype	any (except main)	Manual

Production and Staging

Standard deployment flow. Code goes feature/* -> dev (staging) -> main (production). Runs inside a Farfalla iframe and requires a host to function.

Volpe2 (temporary)

A parallel Cloudflare Pages project used during the Readium 2 migration. Deploys the same production build to a separate URL for side-by-side comparison. Will be removed once the migration is complete.

Prototype (standalone)

A standalone deployment for design iteration and prototyping. Unlike all other environments, the prototype runs without a Farfalla iframe - it loads built-in test content (PDF, EPUB, audiobook) directly.

How it works:

• Uses build:local mode (vite build -m dev), which sets VITE_ENV=local and enables standalone loading
• Dev content files (src/dev-content-files/) are bundled into the build output via viteStaticCopy
• The CI job fetches Git LFS binaries (test content) before building
• No Sentry integration (acceptable for design work)
• CI variable: GV_VOLPE_PROTOTYPE (File-type, based on GV_VOLPE_LOCAL with VITE_URL changed)

The deploy:prototype CI job is available as a manual trigger on any branch (except main), making it easy to deploy any experimental branch for review.

Apps (Fenice)

Built as optimized ZIP artifacts and uploaded to GitLab Package Registry. Fenice (iOS, Android, macOS, Windows) downloads and bundles these builds into its WebView.

Environment	CI Job	Branch	Trigger
Staging	deploy:staging:fenice	dev	Auto (on dev push)
Production	deploy:production:fenice	main	Manual (from main)
Dev test	test:deploy:dev:fenice	any (except main)	Manual

The dev test build uploads with a volpe-developer- prefix to distinguish it from release artifacts.

CI Variables

Each environment uses a dedicated GitLab CI File-type variable for its .env configuration:

Variable	Environment
GV_VOLPE_LOCAL	Local / CI build
GV_VOLPE_STAGING	Staging
GV_VOLPE_PRODUCTION	Production
GV_VOLPE_PROTOTYPE	Prototype
GV_FENICE_STAGING	Fenice staging
GV_FENICE_PRODUCTION	Fenice production

Cloudflare credentials (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID) are separate project-level variables shared across all deploy jobs.