Configuration & Env Variables

Relevant source files

The following files were used as context for generating this wiki page:

• src/server.js
• src/views.js
• README.md
• PLAN.md
• test/app.test.js

PuppyPad uses environment variables to define site metadata, resource limits, security credentials, and infrastructure settings. These variables control the behavior of the Express application, the Caddy reverse proxy, and the screenshot worker.

The application reads these variables at startup to populate a central cfg object. This object then governs system-wide logic such as storage quotas, bandwidth caps, and administrative access.

Sources: src/server.js:15-39, PLAN.md:254-263

Core Application Settings

The application identity and network presence are defined by several key variables. The BASE_URL variable is critical as it establishes the origin for the site and determines if the session cookies use the __Host- prefix for enhanced security.

Variable	Description	Default Value
SITE_NAME	The public name of the hosting service.	PuppyPad
TAGLINE	The slogan displayed in the site header.	accidents welcome
BASE_URL	The full origin URL of the main site.	http://localhost:3000
BASE_DOMAIN	The primary domain used for the app and member subdomains.	(Defined in .env)
OPERATOR	Entity or person running the service.	(Empty)

Sources: src/server.js:16-23, README.md:129-132, PLAN.md:255

Host and URL Logic

The following diagram shows how the application derives hostnames and URLs from the BASE_URL environment variable.

Resource Quotas and Limits

PuppyPad enforces strict resource limits to ensure fair usage across all member sites. These limits are primarily controlled through environment variables that set maximum values for storage and bandwidth.

Variable	Description	Default Value
QUOTA_MB	Maximum storage space allowed per member site.	500
MAX_FILE_MB	Maximum size allowed for a single uploaded file.	5
ZIP_MAX_MB	Maximum allowed size for a ZIP import.	20
BANDWIDTH_MB	Daily bandwidth cap per site (per UTC day).	1024
RENAME_DAYS	Minimum days a user must wait between site renames.	30
NEW_SITE_HOURS	Delay before a new site appears in public listings.	24

Sources: src/server.js:25-32, README.md:26-31

Security and Integration

Security configurations include administrative access lists, CAPTCHA integration, and internal tokens for the screenshot service.

Administrative Access

Administrative rights are granted based on the ADMIN_EMAILS variable. This is a comma-separated list of email addresses. An account only gains administrative privileges if its email matches this list and the email is confirmed.

Sources: src/server.js:33-34, PLAN.md:79-82

Bot and Phishing Protection

PuppyPad integrates with Cloudflare Turnstile to prevent automated signups. The application also uses a SHOT_TOKEN to secure communication with the internal screenshot worker.

Variable	Description	Usage
TURNSTILE_SITE_KEY	Public key for Cloudflare Turnstile.	Used in signup template.
TURNSTILE_SECRET_KEY	Secret key for Turnstile verification.	Used in server-side validation.
SHOT_TOKEN	Shared secret for the screenshot worker.	Authenticates internal requests.

Sources: src/server.js:36-38, PLAN.md:104-106, test/app.test.js:156-174

Email Configuration (SMTP)

Email functionality for confirmations, password resets, and notifications requires a transactional SMTP provider.

Deployment Environment Files

The project uses multiple .env files to separate application configuration from infrastructure secrets.

• .env: Contains application-level variables like BASE_DOMAIN, ADMIN_EMAILS, and SMTP settings.
• .env.caddy: Contains infrastructure secrets such as CF_API_TOKEN, which is used by Caddy to perform DNS-01 challenges for wildcard certificates.

Sources: README.md:131-133, PLAN.md:254-257

Conclusion

The configuration system in PuppyPad prioritizes security and resource management. By utilizing environment variables, administrators can scale storage quotas, adjust security thresholds like Turnstile verification, and manage administrative privileges without modifying the core codebase. These settings are foundational to the application's stability and its ability to host thousands of static sites safely on a single VPS.

Sources: PLAN.md:65-68, src/server.js:15-39