Last indexed: 11 February 2026 (5f6a2a)

Environment Variables (.env)

This document describes the .env file, which contains environment-specific configuration for StaticForge including credentials, server paths, and infrastructure settings. The .env file is loaded during application bootstrap and provides the foundational configuration layer for the system.

For site identity and structure configuration (site name, menus, feature settings), see Site Configuration (siteconfig.yaml). For information about how configuration is resolved across multiple sources, see Configuration Resolution.

Purpose and Scope

The .env file serves as the infrastructure configuration layer for StaticForge. It contains:

Credentials: API keys, passwords, authentication tokens
Environment-specific URLs: Development vs production base URLs
Directory paths: Where to find content, templates, and output
Server configuration: SFTP/S3 deployment settings
Logging configuration: Log levels and file locations

The .env file should never be committed to version control as it contains sensitive credentials and environment-specific settings that differ between development, staging, and production environments.

Sources: .env.example1-42 content/guide/configuration.md15-59

File Location and Creation

The .env file must be located in your project root directory (the same directory that contains composer.json, content/, and templates/).

Initial Setup

The site:init command creates a .env file from .env.example:

Alternatively, manually copy the example file:

Sources: content/guide/quick-start.md40-62 .env.example1-42

Loading Mechanism

Bootstrap Loading Process

Diagram: Environment Variable Loading Flow

The bootstrap process searches for .env in the following order:

Provided path (if passed as parameter to bootstrap)
Current working directory (getcwd()/.env)

Once found, the file is loaded using vlucas/phpdotenv:

src/bootstrap.php64-77

Variables are loaded into the $_ENV superglobal and then copied to the Container for application-wide access.

Sources: src/bootstrap.php46-77 composer.json26

Path Normalization

Relative to Absolute Conversion

StaticForge normalizes all directory paths to absolute paths during bootstrap to ensure consistent path resolution regardless of the working directory.

Diagram: Path Normalization Logic

src/bootstrap.php95-109

The normalization function handles:

Absolute Unix paths: Starting with / (e.g., /var/www/content)
Absolute Windows paths: Matching pattern [A-Z]:\ (e.g., C:\Sites\mysite\content)
Stream wrappers: Containing :// (e.g., vfs://test/content for testing)
Relative paths: All others are prepended with app_root

Application Root Detection

The app_root is determined by traversing upward from the current working directory until finding composer.json or .env:

src/bootstrap.php79-93

If not found, the current directory is used as fallback.

Sources: src/bootstrap.php79-109 content/development/bootstrap.md76-82

Variable Reference

Directory Paths

Variable	Type	Default	Description
`SOURCE_DIR`	Path	`content`	Directory containing content files (`.md`, `.html`)
`OUTPUT_DIR`	Path	`public`	Directory where generated HTML is written
`TEMPLATE_DIR`	Path	`templates`	Directory containing Twig templates
`FEATURES_DIR`	Path	`src/Features`	Directory for custom feature plugins
`LOG_DIR`	Path	`logs`	Directory for log files
`LOG_FILE`	Path	`logs/staticforge.log`	Full path to log file

Path Behavior:

All paths are normalized to absolute paths during bootstrap
Relative paths are resolved relative to project root
Paths support both Unix (/) and Windows (\) separators

Example:

Sources: src/bootstrap.php113-123 .env.example7-11

Site URLs

Variable	Type	Required	Description
`SITE_BASE_URL`	URL	Yes	Full public URL where the site will be hosted (include trailing slash)
`UPLOAD_URL`	URL	No	Production URL used during deployment (if different from `SITE_BASE_URL`)

SITE_BASE_URL Usage:

This is the most critical configuration variable. It is used to:

Generate absolute URLs in HTML output
Construct sitemap.xml entries
Build RSS feed links
Create canonical URLs

Always include the trailing slash:

Template Usage:

Sources: .env.example4-5 content/guide/configuration.md66-90 content/development/templates.md156-176

Template Configuration

Variable	Type	Default	Description
`TEMPLATE`	String	`staticforce`	Name of the template directory to use

Template Resolution:

The template is resolved with the following priority:

siteconfig.yaml (site.template)
.env (TEMPLATE)
Default value (staticforce)

src/bootstrap.php178-186

Example:

Note: For new projects, it is recommended to configure templates in siteconfig.yaml instead of .env. See Site Configuration (siteconfig.yaml).

Sources: src/bootstrap.php126-186 content/development/templates.md189-195

Logging Configuration

Variable	Type	Default	Description
`LOG_LEVEL`	Enum	`INFO`	Logging verbosity level
`LOG_FILE`	Path	`logs/staticforge.log`	Path to log file

Log Levels:

Level	Value	Description
`DEBUG`	Highest verbosity	All operations, variable dumps, internal state
`INFO`	Standard operations	File processing, feature loading, build events
`WARNING`	Potential issues	Deprecated features, configuration warnings
`ERROR`	Critical failures	File read errors, rendering failures
`CRITICAL`	System failures	Fatal errors, bootstrap failures

Environment-Specific Recommendations:

The logger is registered as a singleton service in the Container:

src/bootstrap.php191-205

Sources: src/bootstrap.php125-205 .env.example14-15 content/guide/configuration.md196-225

SFTP Deployment Configuration

These variables configure the site:upload command for deploying via SFTP.

Variable	Type	Required	Description
`SFTP_HOST`	String	Yes	Remote server hostname or IP address
`SFTP_PORT`	Integer	No	SFTP port (default: 22)
`SFTP_USERNAME`	String	Yes	Username for authentication
`SFTP_PASSWORD`	String	No	Password authentication (use password OR private key)
`SFTP_PRIVATE_KEY_PATH`	Path	No	Path to SSH private key file (recommended over password)
`SFTP_PRIVATE_KEY_PASSPHRASE`	String	No	Passphrase for encrypted private key
`SFTP_REMOTE_PATH`	Path	Yes	Destination directory on remote server

Authentication Methods:

StaticForge supports two authentication methods (choose one):

Password Authentication:

Private Key Authentication (Recommended):

Sources: .env.example18-32 content/guide/configuration.md243-275

S3 Media Offload Configuration

These variables configure S3 (or S3-compatible) storage for media file offloading.

Variable	Type	Required	Description
`S3_BUCKET`	String	Yes	S3 bucket name
`S3_REGION`	String	Yes	AWS region (e.g., `us-east-1`)
`S3_ACCESS_KEY`	String	Yes	AWS access key ID
`S3_SECRET_KEY`	String	Yes	AWS secret access key
`S3_ENDPOINT`	URL	No	Custom endpoint for S3-compatible services

AWS S3 Example:

DigitalOcean Spaces Example:

Sources: .env.example34-40

Optional Feature Configuration

Variable	Type	Default	Description
`GOOGLE_ANALYTICS_ID`	String	Empty	Google Analytics tracking ID (e.g., `G-XXXXXXXXXX`)
`SHOW_DRAFTS`	Boolean	`false`	Include files with `draft: true` in builds

Show Drafts:

Controls whether content marked as drafts is included in the build:

Files with draft: true in frontmatter are filtered by FileDiscovery unless SHOW_DRAFTS is enabled.

Sources: .env.example41 content/guide/configuration.md313-326

Default Values and Fallbacks

Default Value Assignment

If a variable is not defined in .env, StaticForge applies sensible defaults during bootstrap:

src/bootstrap.php113-127

Default Values Table:

Variable	Default Value
`SOURCE_DIR`	`content`
`TEMPLATE_DIR`	`templates`
`OUTPUT_DIR`	`public`
`LOG_DIR`	`logs`
`LOG_FILE`	`logs/staticforge.log`
`LOG_LEVEL`	`INFO`
`TEMPLATE`	`staticforce`

Sources: src/bootstrap.php113-127

Environment-Specific Configuration

Development Configuration

Recommended settings for local development:

Sources: content/guide/configuration.md444-455

Production Configuration

Recommended settings for production deployment:

Sources: content/guide/configuration.md457-468

Variable Access Patterns

Accessing Variables in Code

Environment variables are accessible through two mechanisms:

1. Direct $_ENV Access:

Variables remain in $_ENV after loading:

2. Container Variables:

Variables are copied to the Container during bootstrap:

src/bootstrap.php132-141

Best Practice: Use Container access in features and commands for consistency with other configuration sources.

Sources: src/bootstrap.php132-141

Variable Usage by Component

Diagram: Environment Variable Usage Across Components

Key Usage Patterns:

File Discovery: Reads SOURCE_DIR to scan for content files
File Processing: Writes to OUTPUT_DIR after rendering
Template Rendering: Uses TEMPLATE_DIR and TEMPLATE to locate Twig templates
Logging: All components use the shared logger created from LOG_LEVEL and LOG_FILE
URL Generation: SITE_BASE_URL is used throughout for absolute URL construction
Deployment: SFTP_* variables configure upload command; S3_* variables configure media offload features

Sources: src/bootstrap.php1-257 content/development/architecture.md1-246

Version Control and Security

.gitignore Configuration

The .env file must never be committed to version control:

.env.example Template

Maintain .env.example as a template for new developers:

Include all variable names with placeholder values
Document required vs optional variables
Provide example values but never real credentials
Commit to version control for team reference

Example entries:

Sources: .env.example1-42 content/guide/configuration.md465-468

Troubleshooting

Missing Required Variables

If required variables are not set, StaticForge will use defaults but may fail at runtime:

Error Example:

RuntimeException: SITE_BASE_URL is required for URL generation

Solution: Ensure SITE_BASE_URL is defined in .env

Path Resolution Issues

Symptom: Files not found, incorrect directory paths

Common Causes:

Relative path interpretation: The system resolves relative paths from the detected app_root, not the current working directory
Working directory mismatch: Running bin/staticforge.php from the wrong directory

Solution: Use absolute paths or ensure you run commands from project root:

Sources: src/bootstrap.php79-109

Autoloader Not Found

Error:

RuntimeException: Could not find Composer autoloader. Please run "composer install".

Causes:

Dependencies not installed
Running from incorrect directory
Corrupted vendor directory

Solutions:

Sources: src/bootstrap.php25-44

.env Not Loaded

Symptom: Variables not available, using all defaults

Diagnostic:

Common Issues:

File named incorrectly (e.g., env instead of .env)
File in wrong directory
Insufficient read permissions

Sources: src/bootstrap.php64-77

Best Practices

Security

Never commit .env to version control
Use private key authentication over passwords for SFTP
Rotate credentials regularly, especially for production
Restrict file permissions:

Organization

Group related variables with comments:
Document custom variables added by third-party features
Use .env.example as the single source of truth for required variables

Performance

Use relative paths when possible (they're normalized to absolute automatically)
Set appropriate LOG_LEVEL for environment (DEBUG in dev, ERROR in prod)
Avoid redundant variables - use siteconfig.yaml for non-sensitive configuration

Sources: content/guide/configuration.md444-468

Refresh this wiki

URL: https://deepwiki.com/calevans/staticforge/4.1-environment-variables-(.env)