04 — Installing into an existing TYPO3

The ZIP from the customer portal is a whole project, and 03 — DDEV sets that project up from scratch. When you already have a TYPO3 v14 installation — your own hosting, your own deployment, your own site configuration — you take the two extension folders out of the ZIP and leave the rest alone.

This works with and without the demo content, and in both Composer and classic mode. Whether your installation runs under DDEV makes no difference here: you already have your environment, and only the command prefix changes (ddev typo3 … instead of vendor/bin/typo3 …).

0. Back up the database and the project

Do this before you unpack anything. You are adding an extension to a site that already holds someone's content, and two of the steps below write to places there is no undo for: extension:setup performs database migrations and copies files into fileadmin/.

mysqldump -u <user> -p <database> | gzip > backup-$(date +%F).sql.gz
tar czf project-$(date +%F).tar.gz /path/to/project

Under DDEV:

ddev snapshot
ddev export-db --file=backup-$(date +%F).sql.gz

Keep both — the dump alone is not enough. A database restored next to the new extension files is a different state than the one you started from, and the theme's compiled CSS, config/sites/<id>/settings.yaml and fileadmin/ all live outside the database.

1. Take the extensions out of the ZIP

unzip yavi-lucerne.zip -d /tmp/yavi

You need two folders from it:

/tmp/yavi/yavi-lucerne/packages/yavi-core/
/tmp/yavi/yavi-lucerne/packages/yavi-lucerne/

What matters is the folder that directly contains ext_emconf.php — that is the extension.

If you also want the demo content, keep the ZIP around: step 4a needs .tarballs/yavi-lucerne-demo.t3d from it.

2a. Composer mode — a path repository

The way the delivery is meant to be used. Put both folders under packages/:

packages/yavi-core/
packages/yavi-lucerne/

Then add the path repository to your project's composer.json and require the two packages:

{
  "repositories": [
    { "type": "path", "url": "./packages/*" }
  ],
  "require": {
    "webagentur-yahya/yavi-core": "dev-main",
    "webagentur-yahya/yavi-lucerne": "dev-main"
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}

The version is dev-main, not a range like ^1.0 or *. The packages come out of a ZIP rather than from a tagged repository, so the path repository has no tag to read a version from and offers them as the branch version dev-main — a dev stability. Under Composer's default minimum-stability: stable that version is invisible, and "*" fails with could not find a version matching your minimum-stability. Hence the two extra keys: minimum-stability: dev makes the branch version acceptable, and prefer-stable: true keeps everything else — TYPO3, Bootstrap Package, your own dependencies — on stable releases.

composer update "webagentur-yahya/*"
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

composer update, not composer install. You edited composer.json by hand, so the lock file does not know about the two new packages yet; composer install installs what the lock file already contains and would either do nothing or refuse to run. Limiting the update to webagentur-yahya/* keeps every other dependency at the version your lock file pins.

extension:setup activates the extensions, performs the database migrations — a good dozen columns on tt_content, plus the carousel, card and portfolio item tables — and copies the initial files. There is no database:updateschema command in TYPO3 v14; that one comes from typo3_console and is not part of the core. extension:setup does that work.

Composer symlinks packages/* into vendor/, so editing a template takes effect immediately — no copy step, no watcher.

Bootstrap Package 16 is a hard dependency and is not in the ZIP. Composer resolves it from packagist as usual, so your project needs network access to packagist even though the Yavi packages do not come from there.

2b. Classic mode

For installations without Composer. It works, but you take over the dependency management Composer would otherwise do for you.

typo3conf/ext/container/
typo3conf/ext/bootstrap_package/
typo3conf/ext/yavi-core/
typo3conf/ext/yavi-lucerne/

Activate them in that order in Admin Tools → Extensions, then run typo3/sysext/core/bin/typo3 extension:setup — note that in classic mode the binary is there and not in vendor/bin/.

Classic mode differs from the Composer path in more places than this — the document root, where site configurations live, and how an extension is activated at all. 04b — Installation in classic mode walks through the whole path and lists every differing path in one table.

Every path below that mentions packages/yavi-lucerne/ is typo3conf/ext/yavi-lucerne/ in classic mode.

3. What activation does, and what it does not

On first activation of the extensions:

The media copy runs once per extension and is remembered in sys_registry under extensionDataImport, so it does not repeat on the next extension:setup.

That copy is not what the demo content uses. The demo's file records point at fileadmin/dummy-media/…, and the import in step 4a brings its own copies of the files it needs. fileadmin/yavi_lucerne/ is there so you have the material at hand; if you do not want it on a production site, delete the folder after the install — the registry entry keeps it from coming back.

4. Decide on the demo content

4a. With the demo content

The demo for an existing installation is .tarballs/yavi-lucerne-demo.t3d from the ZIP — an impexp content package, 27 MB, with all its images, videos and audio inside the file. It is not the database dump, and it replaces nothing: it adds a new page tree at the root level and leaves your own pages, content and users alone.

Copy the file into your project and import it:

mkdir -p .tarballs
cp /tmp/yavi/yavi-lucerne/.tarballs/yavi-lucerne-demo.t3d .tarballs/
vendor/bin/typo3 impexp:import /full/path/to/project/.tarballs/yavi-lucerne-demo.t3d 0

Under DDEV the path is the one inside the container:

ddev typo3 impexp:import /var/www/html/.tarballs/yavi-lucerne-demo.t3d 0

It takes about ten seconds and ends with

 [OK] Importing … succeeded.

Afterwards you have a second root page named Home next to your own, with 59 pages, 233 content elements and 194 media files below it. Continue with step 5 — the new tree needs its own site configuration before it will render.

Through the backend instead. If you would rather not use the command line, the same file goes through Import/Export: put it in fileadmin/user_upload/_temp_/importexport/, then right-click the root of the page tree, choose More options → Import, pick the file and run the import. Uploading a 27 MB file through the form needs upload_max_filesize and post_max_size to allow it; copying the file into that folder over SFTP avoids the question.

What the demo package does not contain. The demo's second language is not in this file — only the default language. TYPO3 synchronises translations while it is resolving the imported relations, and doing so on an import of this size ends in an error that aborts the whole import without naming a cause. The loss is small: the demo's second language covers 1 of its 60 pages, and its text is English anyway. A fresh installation set up from the database dump (03, 03b) has every translation, because a dump is a dump.

4b. Without the demo content

Nothing to do. The extensions carry no content import, so your page tree is already exactly as it was. Continue with step 5.

The theme's appearance does not come from the demo database. It comes from the Set and the settings in config/sites/<id>/settings.yaml, which is what 05 — Setting up the first site walks through. An empty site with the Set activated and a valid licence renders in the theme's design from the first page you create.

5. The site configuration

TYPO3 only imports a package's Initialisation/Site/ together with an Initialisation/data.t3d/data.xml content import — the importer returns early without one. Since the extensions ship no import file, Initialisation/Site/ is never applied automatically.

A site folder holds three files, and the theme needs all three:

TYPO3 picks up page.tsconfig and settings.yaml on its own as soon as they sit in the site folder — there is nothing to include anywhere.

Without the demo (4b), keep the site configuration you have and add the missing pieces to it. First the Sets: in config/sites/<id>/config.yaml, extend the dependencies key — order matters, each builds on the one above it:

dependencies:
  - bootstrap-package/full
  - yavi-core/full
  - yavi-lucerne/full

The same list is editable in the backend under Site Management → Sites. Keep everything else — base, languages, error handling — as it is. Do not copy the shipped config.yaml over a configured site; it would reset all of it.

Then the other two files, which your site does not have yet:

cp packages/yavi-lucerne/Initialisation/Site/yavilucerne/page.tsconfig \
   packages/yavi-lucerne/Initialisation/Site/yavilucerne/settings.yaml \
   config/sites/<id>/

Flush the cache afterwards; the Sets bring TypoScript with them.

Then give your root page a backend layout: Page properties → Appearance → Backend Layout (this page only) and (subpages of this page), both set to Yavi Core - Default. Your existing pages have whatever layout they had before, which is none of the theme's — without this they have no columns the theme addresses, and the frontend renders an empty frame. See 05 — Setting up the first site.

With the demo (4a), the imported tree is a new root page and needs a site configuration of its own. The shipped one is a usable starting point:

mkdir -p config/sites/demo
cp -R packages/yavi-lucerne/Initialisation/Site/yavilucerne/. config/sites/demo/

Then edit config/sites/demo/config.yaml:

The base has to be absolute. With a relative /demo/ next to an existing site whose base carries the host, TYPO3 does not match the request to the new site and answers every URL below it with a 404.

Remove the baseVariants block unless you are on DDEV — it carries %env(DDEV_BASE)% placeholders that resolve to nothing anywhere else.

The licence key in the shipped settings.yaml is empty on purpose, so no key is ever distributed. Enter yours as described in 05 — Setting up the first site.

6. Check file permissions

The web server user must be able to write:

• config/sites/<id>/settings.yaml — otherwise the backend module cannot save
• typo3temp/assets/ — otherwise the compiled CSS cannot be written
• var/cache/
• fileadmin/ — for uploads and for the self-hosted Google fonts feature

7. Continue

Activate the Set and enter the licence — 05 — Setting up the first site.

Updating

New versions come from **licence.yavithemes.com → Konto → Downloads**. Use the Framework update there — yavi-core-<version>.zip, around 5 MB. The full package is for a first installation. The page shows an Updates until date per licence; the site keeps running when it passes, an expired window blocks new versions, not what is installed.

Only yavi-core is updated. The theme extension is yours — its SCSS, its templates, its settings — and an update must not overwrite that work.

1. Back up the database and the project, exactly as in step 0. An update runs the database migrations again, and a schema change is not something you can undo by putting the old files back.
2. Put the site into maintenance mode, or accept a few seconds of broken layout.
3. Delete the old yavi-core folder — do not unpack over it. Files that the new version removed would otherwise stay behind, and a leftover SCSS partial that is still @imported somewhere is a hard error to track down.
4. Unpack the new version into the same place. Leave the theme folder alone.
5. In Composer mode, run composer dump-autoload so the autoloader picks up new PHP classes.
6. vendor/bin/typo3 extension:setup && vendor/bin/typo3 cache:flush

The cache flush is not optional. The compiled theme-<hash>.css is keyed by the SCSS content, and without a flush the old file keeps being served.

An update never touches content. Neither the demo import nor your own pages are affected by it.

Known limitations of classic mode