Installation

You’ll be up and running in under 5 minutes. The setup wizard handles everything after the initial command.

Composer install (recommended)

composer create-project totalcms/totalcms my-site

This downloads Total CMS into my-site/, then runs a short post-install script that asks you a few setup questions. Make sure your server meets the System Requirements before installing.

What the install asks

After Composer finishes downloading, you’ll be prompted with up to three questions.

1. Layout

Where T3 lives in your URL space.

Choice	What it does	Pick this if…
root (default)	T3 owns the whole domain. Front controller at public/index.php; requests go to T3 by default	T3 is your whole site
subpath	T3 lives at /tcms/. public/ is free for your own frontend build	You’re using T3 as a headless CMS alongside a separate frontend (Next.js, Astro, static, etc.)

Picking subpath moves public/index.php and public/.htaccess into public/tcms/ automatically.

2. Starter pack (root layout only)

A starter pre-seeds your install with sample pages and content so you have something to look at right away. Bundled starters:

Starter	What you get
minimal	A blank canvas. Empty page tree, no demo content
blog	Blog homepage, post layout, sample posts
business	Homepage with sections, about page, contact form
portfolio	Project gallery layout with sample entries

Pick none if you want a fully empty install. You can run tcms builder:init <starter> later to apply one.

3. Frontend pipeline (root layout only)

A Vite-based bundle for compiling your site’s CSS and JS, drops a frontend/ directory at the project root that you can npm install into. Builder layouts can reference compiled assets via {{ cms.builder.css(...) }}.

Default: no. You can add it later with tcms builder:frontend.

After the install

1. Point your web server’s document root to my-site/public/
2. Visit your site in a browser:
   • Root layout: visit /
   • Subpath layout: visit /tcms/

The setup wizard starts automatically.

Non-interactive installs

For CI or scripted installs, set environment variables and the prompts use those instead of asking:

Variable	Values	Default
TCMS_LAYOUT	root | subpath	root
TCMS_STARTER	none | minimal | blog | business | portfolio	none
TCMS_FRONTEND	0 | 1	0

TCMS_LAYOUT=root TCMS_STARTER=blog TCMS_FRONTEND=1 \
  composer create-project totalcms/totalcms my-site --no-interaction

Alternative: zip download

If Composer isn’t available — shared hosting, restricted environments, or you just prefer file uploads — install from a zip.

Total CMS goes in a folder of its own inside your existing site. Your pages and assets stay outside it, and your document root does not move.

1. Download the Total CMS zip from totalcms.co

2. Extract it into a folder inside your site. tcms/ is the convention:

   yoursite.com/            # your document root — unchanged
   ├── index.php            # your pages
   ├── styles/  images/     # your stylesheets, scripts, fonts, media
   └── tcms/                # Total CMS lives here, and only here

3. Leave your document root pointing at your site — not at anything inside tcms/

4. Visit /tcms/ — the setup wizard starts automatically

5. At the data-path step, take the default. tcms-data/ belongs beside the tcms/ folder, not inside it

Nothing of yours goes inside tcms/.

An update replaces that folder’s contents wholesale — it installs the new release’s config/, public/, resources/, src/ and vendor/ over the old ones rather than merging file by file. A folder you add inside any of those is removed along with its parent. Your own stylesheets, scripts, fonts, images and video belong in your site, outside tcms/. See Updates for exactly what an update replaces and what it leaves alone.

Apart from where the files sit, the zip workflow is identical to Composer: same wizard, same admin, same update flow.

Setup wizard

When you first visit your install URL, the wizard runs through these screens.

1. Welcome

Choose your preferred language for the admin interface:

Code	Language
en_US	English (US)
en_GB	English (UK)
de_DE	Deutsch
es_ES	Español
it_IT	Italiano
nl_NL	Nederlands
pl_PL	Polski

This setting only affects the admin. Your public-facing site uses its own translations.

2. Environment check

The wizard verifies your server meets the System Requirements. All required PHP extensions must pass; recommended ones show as suggestions.

If something’s missing, you’ll see exactly what to install. Fix it, refresh, and the check re-runs automatically.

3. Data path

Choose where Total CMS stores your content. This directory is separate from the application — updates never touch your content.

Option	Path	When to choose
Document Root	<docroot>/tcms-data	Simplest. Works on every host
Above Document Root	<parent>/tcms-data	Recommended for production — keeps content outside the web tree
Custom Path	Any absolute path	When the defaults don’t fit your hosting setup

If the data directory ends up inside your docroot, T3 drops an .htaccess in it that blocks direct web access.

4. Admin account

Create your first administrator account. You’ll log in with these credentials every time.

This account has full privileges, including installing extensions and modifying schemas — pick a strong password.

5. License

Your license is validated automatically. New installations start with a free trial; if you’ve already purchased a license for this domain, it’s detected on first run.

Local development domains are free. On localhost, 127.0.0.1, or any .localhost or .test domain, Total CMS runs with every Pro feature and needs no trial or license key. A .local domain is not one of them and starts a normal trial. See Development Domains.

You can change the license later from Settings → License Manager in the admin.

6. Error monitoring

Choose whether Total CMS may report application errors to the developer. Leaving this on means bugs get discovered and fixed quickly — often before you notice anything went wrong, and without you having to file a report.

Reports contain only the error and where it occurred in the code. No content, credentials, or private data ever leaves your server — the reporting client is explicitly configured to never attach request bodies, cookies, session data, or IP addresses. See Error Monitoring for the full details.

You can change this choice at any time in Settings → General (“Share Application Errors with Developer”).

7. Server config

The wizard renders the exact rewrite-rule snippets you need for your server. For Composer installs, the Apache rules ship in .htaccess automatically — the wizard tells you everything’s already in place. For other servers (Nginx, Caddy), copy the snippet into your server config and reload.

You’re done

After the wizard completes, you land in the admin dashboard. From here:

• Follow the Your First Site tutorial to add content and render it on a public page (about 10 minutes)
• Or take the Dashboard tour for an overview of the admin

Directory structure

The application and your content are deliberately separate, and the shape differs slightly between the two install methods.

Composer install

Total CMS owns the domain, and the document root points inside the application at public/.

/var/www/example.com/
├── my-site/                  # Application
│   ├── config/               # Configuration files
│   ├── public/               # Web root — point your server here
│   │   ├── index.php         # Entry point
│   │   └── assets/           # CSS, JS, images
│   ├── resources/            # Templates, schemas, translations, docs
│   ├── src/                  # PHP source
│   ├── vendor/               # Composer dependencies
│   └── version.json          # Version info
└── tcms-data/                # Your content (separate from the app)
    ├── .schemas/             # Custom schema definitions
    ├── .system/              # Settings, API keys
    ├── builder/              # Site Builder templates
    ├── templates/            # Custom Twig templates
    └── [collections]/        # Collection data (blog, gallery, etc.)

Composer installs update with composer update totalcms/cms, which resolves files individually — so the built-in updater’s whole-directory replacement does not apply here.

Zip install

Total CMS sits in a folder inside your site. Your document root stays on your own site, and tcms-data/ sits beside the application rather than inside it.

/var/www/example.com/         # your document root
├── index.php                 # your pages
├── styles/  images/          # your stylesheets, scripts, fonts, media
├── tcms/                     # Application — replaced wholesale on update
│   ├── config/  public/  resources/  src/  vendor/
│   ├── cache/  logs/  tmp/   # runtime, left alone by updates
│   └── version.json
└── tcms-data/                # Your content — never touched by updates

Everything of yours lives outside tcms/. An update replaces that folder’s contents, so it is not a place to keep anything you authored. See Updates.

Web server configuration

Most servers work out of the box. Reference configs below.

Apache

T3 ships an .htaccess for URL rewriting. Just ensure mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl reload apache2

A minimal virtual host:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example.com/my-site/public

    <Directory /var/www/example.com/my-site/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx

Nginx needs a full server block with explicit rewriting and PHP-FPM proxying. See Nginx Configuration for the complete reference.

Caddy and FrankenPHP

Both work like Nginx via PHP-FPM (or FrankenPHP’s classic mode). Point them at public/index.php with a standard PHP fastcgi proxy and a try_files-style fallback for routing.

LiteSpeed

Works out of the box using the bundled .htaccess. No extra config needed.

CLI

T3 ships with a CLI tool for routine operations — collection management, JumpStart imports, cache clearing, and more:

php my-site/resources/bin/tcms info

See CLI Commands for the full reference.

Troubleshooting

Setup wizard doesn’t appear

Your web server is pointing at the wrong directory. T3’s web root is my-site/public/, not my-site/. Update your virtual host’s DocumentRoot and reload.

Permission denied errors

The web server user (www-data on Debian/Ubuntu, apache on RHEL/CentOS) needs write access to:

• tcms-data/
• my-site/cache/
• my-site/logs/
• my-site/tmp/

sudo chown -R www-data:www-data tcms-data my-site/{cache,logs,tmp}

Required extension missing

The wizard tells you which one. On Debian/Ubuntu:

sudo apt install php8.2-{extension}
sudo systemctl reload apache2   # or php8.2-fpm

Refresh the wizard — the check re-runs automatically.

Blank page or 500 error

Check my-site/logs/ for specific error messages. Common causes:

• PHP version below 8.2
• A required extension didn’t reload after install
• File permissions on tcms-data/ or my-site/cache/

404 on every page

URL rewriting isn’t working.

• Apache: verify mod_rewrite is enabled and the virtual host has AllowOverride All
• Nginx / Caddy / FrankenPHP: check the try_files directive — see Nginx Configuration

License validation fails

• Verify curl is installed (php -m | grep curl)
• Confirm outbound HTTPS from the server isn’t blocked by a firewall
• Make sure the domain you’re installing on matches your license

Getting help

If something’s still not working:

1. Check my-site/logs/ for specific error messages
2. Search the Community Forum
3. Review the Deployment Guide for production-specific issues