Safe and Reproducible Version Control Architecture for TYPO3 CMS

TYPO3 is an enterprise open-source Content Management Framework renowned for its extensibility, multi-site architecture, and strict security posture. However, deploying a fresh TYPO3 instance to a live Linux server (e.g., at /var/www/html/typo3) frequently leaves engineering teams with a critical architectural dilemma: How do we apply Version Control Systems (VCS) to a live system without breaking its runtime integrity or leaking sensitive infrastructure credentials?

A professional VCS architecture ensures that a project can be cloned by any engineer, deployed through automated CI/CD runners, and recovered after hardware failure with 100% deterministic reproducibility.

Enterprise CMS architecture divides a running website into four orthogonal tiers. Only two of these tiers belong in Git.

In TYPO3 v12 and v13, the primary configuration array resides in settings.php (located at typo3conf/system/settings.php in Classic mode or config/system/settings.php in Composer mode). By default, this file stores sensitive parameters in plain text:

The Decoupling Strategy: additional.php + Environment Variables

TYPO3 provides a dedicated bootstrap hook: immediately after loading settings.php, it checks for and executes additional.php. We utilize this to inject infrastructure secrets at runtime without hardcoding them into tracked files.

<?php
defined('TYPO3') or die('Access denied.');

/**
 * Enterprise Secret Isolation Layer
 * Reads infrastructure credentials dynamically from OS environment or .env
 */
$dbHost = getenv('TYPO3_DB_HOST') ?: '127.0.0.1';
$dbName = getenv('TYPO3_DB_NAME') ?: 'typo3';
$dbUser = getenv('TYPO3_DB_USER') ?: 'typo3';
$dbPass = getenv('TYPO3_DB_PASSWORD');

if ($dbPass !== false) {
    $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host'] = $dbHost;
    $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['dbname'] = $dbName;
    $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['user'] = $dbUser;
    $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['password'] = $dbPass;
}

// Ensure Install Tool password hash can also be injected via environment
if ($installToolHash = getenv('TYPO3_INSTALL_TOOL_PASSWORD')) {
    $GLOBALS['TYPO3_CONF_VARS']['BE']['installToolPassword'] = $installToolHash;
}

Below is the definitive, field-tested .gitignore configuration tailored specifically for modern TYPO3 installations running under Linux.

# ==============================================================================
# Enterprise TYPO3 v13 Version Control Rules
# ==============================================================================

# 1. Credentials and Environment Variables
.env
.env.*
!.env.example
typo3conf/system/settings.php

# 2. Uploaded Media & Binary Storage (Managed via independent backup)
/fileadmin/
!/fileadmin/.gitkeep

# 3. Volatile Cache, Transpiled Assets, and Compilations
/typo3temp/*
!/typo3temp/.gitkeep
/var/cache/
/var/log/
/var/lock/

# 4. Core & External Dependencies (Installed via Composer / Release Archive)
/vendor/
/typo3/
/bin/

# 5. Localization / Translation Data (Downloaded from Crowdin)
/typo3conf/l10n/

# 6. Third-Party Extensions (Track only YOUR in-house site package)
/typo3conf/ext/*
!/typo3conf/ext/site_package/
!/typo3conf/ext/*_sitepackage/

# 7. Operating System & IDE Artifacts
.DS_Store
Thumbs.db
.idea/
.vscode/
*.log
*.sql
*.tar.gz

A common legacy mistake is configuring TYPO3 templates through the backend Database Template module (SysTemplate) and storing CSS/JS files directly inside fileadmin/.

The Sitepackage Pattern encapsulates all visual design, layout logic, custom content elements, and configurations into a dedicated, version-controlled extension:

typo3conf/ext/site_package/
├── Configuration/
│   ├── TypoScript/
│   │   ├── setup.typoscript
│   │   └── constants.typoscript
│   └── Sets/SitePackage/
├── Resources/
│   ├── Private/
│   │   ├── Layouts/
│   │   ├── Partials/
│   │   └── Templates/
│   └── Public/
│       ├── Css/
│       ├── Js/
│       └── Icons/
├── composer.json
└── ext_emconf.php

When evaluating a deployment at /var/www/html/typo3, engineers must understand the distinction between TYPO3's two operational modes:

my-typo3-project/                  <-- Repository Root (Forbidden to Web Server)
├── .git/
├── .gitignore
├── composer.json                 <-- Defines exact TYPO3 v13 versions & packages
├── composer.lock                 <-- Lockfile guarantees bit-for-bit parity
├── config/
│   ├── sites/main/config.yaml    <-- Tracked routing
│   └── system/additional.php     <-- Environment secret overrides
├── packages/
│   └── site_package/             <-- Tracked custom extension
└── public/                       <-- DocumentRoot exposed to Nginx (/var/www/...)
    ├── index.php
    ├── typo3/                    <-- Symlinked backend entry point
    ├── typo3temp/                <-- Runtime temporary files
    └── fileadmin/                <-- User uploads storage

Follow this exact execution protocol on your server to establish a clean Git repository on your existing site:

cd /var/www/html/typo3
pwd
# Check if git is already initialized
git status

# Create .env.example for team reference
cat << 'EOF' > /var/www/html/typo3/.env.example
TYPO3_DB_HOST=127.0.0.1
TYPO3_DB_NAME=typo3
TYPO3_DB_USER=typo3
TYPO3_DB_PASSWORD=your_secure_password_here
TYPO3_CONTEXT=Production
EOF

# Initialize Git
git init -b main

# Stage configuration and safety files
git add .gitignore .env.example typo3conf/sites/ typo3conf/PackageStates.php

# Verification: Confirm that fileadmin, typo3temp, and settings.php are IGNORED
git status --ignored

git commit -m "chore: initial TYPO3 v13 configuration and site baseline"

One of the most frequent misconceptions in CMS DevOps is attempting to track database SQL dumps directly inside Git.

Running git pull directly on a production server is dangerous. If a pull encounters a network timeout, merge conflict, or syntax error, the live site remains broken for users. Furthermore, file permissions between CLI users and www-data easily desynchronize.

The Symlink-Based Deployment Pipeline

Tools like Deployer (PHP), Ansible, or GitHub Actions execute zero-downtime releases using atomic directory symlinks:

/var/www/typo3-app/
├── current -> releases/20261015143000   <-- Nginx DocumentRoot
├── releases/
│   ├── 20261015120000/
│   └── 20261015143000/                 <-- New release built & prepared
└── shared/
    ├── .env
    └── fileadmin/                      <-- Shared persistent storage