Installation & Project Setup

This document covers the installation of StaticForge via Composer, the site:init command for project initialization, and the directory structure created during setup. For detailed information about the purpose of each directory, see Project Structure. For basic usage after installation, see Basic Usage.

Prerequisites

StaticForge requires:

• PHP 8.4 or higher - specified in composer.json14
• Composer - for dependency management and installation
• Command-line access - for running CLI commands

Installation Methods

StaticForge can be installed in two ways depending on your use case:

Library Installation (Recommended)

For creating new static sites, install StaticForge as a dependency:

This command installs StaticForge into vendor/eicc/staticforge/ and makes the staticforge.php CLI available via Composer's bin directory (composer.json57-59). The installation process automatically triggers template installation via a Composer plugin.

Automatic Template Installation: The package includes eicc/staticforge-installer (composer.json15) which is configured as an allowed plugin (composer.json53-55). This plugin executes scripts/install-templates.php1-108 during composer install or composer update, copying default templates from the package to your project's templates/ directory without overwriting existing files.

Development Installation

For contributing to StaticForge core or developing custom features:

This clones the full repository including source code, tests, and documentation. The README.md23-32 documents this installation method.

Diagram: Installation Flow

Sources: composer.json1-60 scripts/install-templates.php1-108 README.md12-19

The site:init Command

After installation, initialize your project structure using the site:init command:

For development installations:

The command is implemented in src/Commands/InitCommand.php1-238 and performs the following operations:

Command Options

Option	Short	Description
--force	-f	Overwrite existing files (InitCommand.php20-25)

Without --force, the command preserves existing files and shows a note (InitCommand.php101-103).

Initialization Process

Diagram: site:init Execution Flow

Sources: src/Commands/InitCommand.php1-238

Directory Creation

The command creates the following directories (InitCommand.php36-42):

Directory	Purpose	Reference
content/	Source content files (.md, .html)	See 2.2
templates/	Twig template files	See 6.1
public/	Generated static HTML output	See 2.2
config/	Optional configuration files	-
logs/	Application log files	See 4.1

Each directory is created with 0755 permissions (InitCommand.php46). If directories already exist, the command displays a note and continues.

Template Installation

The copyBundledTemplates() method (InitCommand.php77-89) locates StaticForge's bundled templates using findVendorPath() (InitCommand.php220-237), which searches multiple possible locations:

1. __DIR__ . '/../../' - development installation
2. getcwd() . '/vendor/eicc/staticforge/' - library installation
3. __DIR__ . '/../../../../../eicc/staticforge/' - alternative vendor structure

Once found, recursiveCopy() (InitCommand.php188-218) copies all template files from the package to the project's templates/ directory. Files are copied only if they don't already exist in the target location (InitCommand.php210-213).

Configuration File Creation

.env File

The command searches for .env.example in two locations (InitCommand.php93-99):

1. Current directory
2. StaticForge package directory

If found and .env doesn't exist (or --force is used), the example file is copied to .env (InitCommand.php106-108). The .env file contains infrastructure configuration. See Environment Variables (.env) for detailed documentation.

siteconfig.yaml File

Similarly, the command searches for siteconfig.yaml.example (InitCommand.php117-122) and copies it to siteconfig.yaml (InitCommand.php129-131). This file contains site-specific configuration like menus and site metadata. See Site Configuration (siteconfig.yaml) for detailed documentation.

Sample Content

If content/index.md doesn't exist, the command creates a welcome page with frontmatter and sample content (InitCommand.php146-182). The generated content includes:

• YAML frontmatter with title, description, and template fields
• Markdown content with headings, lists, and links
• Instructions for next steps

Sources: src/Commands/InitCommand.php91-186

Directory Structure Created

After running site:init, your project structure looks like this:

Diagram: Project Directory Structure

Sources: src/Commands/InitCommand.php36-51 .env.example7-10

Configuration Files

.env File Structure

The .env file contains environment-specific configuration. Example structure from .env.example1-42:

Variable	Purpose	Example
SITE_BASE_URL	Base URL for generated site	http://localhost:8000/
UPLOAD_URL	Production URL	https://example.com
SOURCE_DIR	Content directory path	content
OUTPUT_DIR	Output directory path	public
TEMPLATE_DIR	Template directory path	templates
LOG_LEVEL	Logging verbosity	INFO
SFTP_*	SFTP upload credentials	Various
S3_*	S3 bucket configuration	Various

These variables are loaded by the bootstrap process (bootstrap.php63-77) into the $_ENV superglobal. Paths are normalized to absolute paths (bootstrap.php111-123).

Important: The .env file contains secrets and should not be committed to version control. It's listed in .gitignore.

siteconfig.yaml Structure

The siteconfig.yaml file contains version-controlled site configuration:

This file is parsed during bootstrap (bootstrap.php143-168) and stored in the container as site_config (bootstrap.php171). See Site Configuration (siteconfig.yaml) for complete documentation.

Sources: .env.example1-42 src/bootstrap.php143-171

Bootstrap Process

When StaticForge runs, the bootstrap process (bootstrap.php1-258) initializes the application:

Diagram: Bootstrap Initialization Sequence

Sources: src/bootstrap.php1-258 composer.json38-42

Path Normalization

The bootstrap process normalizes all directory paths to absolute paths using a helper function (bootstrap.php96-109):

Normalization Logic:

1. Paths starting with / (Unix) or X:\ (Windows) are treated as absolute
2. Paths containing :// are treated as stream wrappers (e.g., vfs:// for testing)
3. All other paths are relative and prepended with app_root

This ensures consistent path resolution regardless of the working directory when executing bin/staticforge.php.

Example:

• Input: content (relative)
• App root: /var/www/mysite/
• Output: /var/www/mysite/content

Sources: src/bootstrap.php96-109

Verification

After initialization, verify your setup:

1. Check directory structure:

2. Verify configuration files:

3. Check sample content:

4. List available commands:

The project is now ready for content creation and site generation. Proceed to Basic Usage to learn how to generate your site.

Sources: README.md36-67 src/Commands/InitCommand.php65-72

Summary

The installation process consists of:

1. Composer installation - Downloads and installs the package (composer.json1-60)
2. Automatic template installation - Copies default templates (scripts/install-templates.php1-108)
3. Project initialization - Creates directory structure and configuration files (InitCommand.php1-238)
4. Bootstrap configuration - Loads environment and initializes services (bootstrap.php1-258)

For information about the purpose of each directory, see Project Structure. For next steps on creating content and generating your site, see Basic Usage.

Sources: composer.json1-60 src/Commands/InitCommand.php1-238 src/bootstrap.php1-258 README.md1-95