Development Environment Setup

Relevant source files

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

• package.json
• README.md
• src/server.js
• PLAN.md
• test/app.test.js

The PuppyPad development environment provides the tools necessary to run and test the homepage hosting platform locally. This setup includes a Node.js Express application, a SQLite database, and an optional screenshot worker using Playwright.

Developers use this environment to simulate the production environment, including subdomain routing and member site rendering. The system stores all site data, including the database and user-uploaded files, within a local ./data directory.

Sources: README.md:1-5, PLAN.md:16-29

Prerequisites

You must install several system dependencies before configuring the PuppyPad repository.

1. Node.js: Use a current version to execute the server and test suite.
2. npm: Manage JavaScript dependencies defined in package.json.
3. Browsers: Install Chromium for the Playwright screenshot worker.
4. Local Networking: Access to your operating system's hosts file to configure test subdomains.

Sources: package.json:12-25, README.md:275-285

Initial Installation

Configure the local environment by cloning the repository and installing package dependencies.

1. Clone the repository to your local machine.
2. Run npm install in the project root to install core dependencies like express, better-sqlite3, and multer.
3. Navigate to the shots/ directory and run npm install to set up the screenshot worker requirements.

Sources: package.json:12-20, README.md:275-277, README.md:281-282

Environment Configuration

PuppyPad uses environment variables for system behavior and security. Define these variables in your terminal session or a .env file.

Required Variables

Variable	Description	Default/Example
BASE_URL	The full origin of your local instance.	http://localhost.test:3000
ADMIN_EMAILS	Comma-separated list of confirmed admin emails.	me@example.com
SHOT_TOKEN	Security token for the screenshot worker API.	A random hex string
DATA_DIR	Path to store the SQLite DB and member files.	./data

Sources: src/server.js:25-45, README.md:276-277, test/app.test.js:10-18

Optional Feature Variables

• QUOTA_MB: Sets the disk space limit per member (default 500).
• MAX_FILE_MB: Sets the maximum size for a single uploaded file (default 5).
• TURNSTILE_SITE_KEY: Enables Cloudflare Turnstile captcha on signup.
• SMTP_HOST: Configures real email delivery. If unset, mail links appear in console logs.

Sources: src/server.js:31-40, README.md:280-281

Running the Application

Execution requires starting both the main Express app and the screenshot worker.

Main Server

Execute the server using Node.js. Provide the BASE_URL and ADMIN_EMAILS directly or via environment.

BASE_URL=http://localhost.test:3000 ADMIN_EMAILS=me@example.com node src/server.js

Sources: README.md:276-277

Screenshot Worker

The screenshot worker requires a running instance of the main app and a matching SHOT_TOKEN.

cd shots && APP_URL=http://localhost:3000 SHOT_TOKEN=x node worker.js

Sources: README.md:281-283

Local Domain Setup

PuppyPad routes requests based on the Host header to serve member subdomains. You must map these domains to your local loopback address.

The diagram shows how the application differentiates between the management interface and hosted member sites based on the hostname.

Sources: src/server.js:133-145, README.md:279-280

Add the following entries to your /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows) file:

• 127.0.0.1 localhost.test
• 127.0.0.1 name.localhost.test (replace 'name' with your test site name)

Sources: README.md:279-280

Testing and Verification

The repository includes a comprehensive test suite using node:test and supertest.

Execution

Run the automated tests to verify the environment:

npm test

Sources: package.json:8, README.md:287-289

Test Coverage

The suite validates critical security and functional components.

Component	Validation Logic
Path Safety	Prevents traversal outside site folders.
Security	Checks CSRF tokens and Origin headers.
Quota	Enforces QUOTA_MB and file type allowlists.
Phishing	Detects suspicious HTML patterns.

Sources: test/app.test.js:38-70, README.md:287-289

Summary

The Development Environment Setup establishes a local instance of PuppyPad using Node.js and SQLite. Developers configure environment variables to define site limits and administrative access. By modifying the system hosts file, you enable the subdomain routing necessary for testing member sites and management dashboards.

Sources: README.md:275-289, PLAN.md:16-29