03 — Installation with DDEV

The recommended path, and the one the delivery is built for. What you download is not an extension but a complete TYPO3 project: unpack it, run one script, and a working site is up — including the demo content. You start from a finished standard site and adapt it, instead of building one from an empty page tree.

The installation on video

The video loads from YouTube only once you press play — nothing is requested before that (why).

What you receive

Log in at licence.yavithemes.com, then Konto → Downloads. Every active licence has one ZIP, named after the product code — yavi-lucerne.zip for Lucerne. It contains the theme, the core extension and the project around them:

There is no config/sites/ in the archive. The site configuration travels as a template inside the theme, and the installer copies it to the site identifier you choose. That also keeps the licence key out of the package — the shipped template carries an empty one.

Prerequisite

A running DDEV with Docker. Installing and configuring DDEV itself is your side of the setup and not covered here — follow DDEV's own documentation. Everything else the project needs, Composer, PHP and the database, runs inside the container.

Once ddev is available on the command line, the rest of this chapter is the whole installation.

1. Unpack and run

The archive already contains a folder of its own, so unpack it where it should live and step into it:

unzip yavi-lucerne.zip
cd yavi-lucerne
chmod +x init-yavi.sh
./init-yavi.sh

The script is interactive and asks eight questions:

The last three are asked at the end, after the database exists. Everything else comes from the environment file, and the script writes your answers back into it, so a second run remembers them.

Entering the licence key up front

Optional, and it saves a step later. Put the key into the environment file before you start:

LICENCE_KEY="XXXX-XXXX-XXXX-XXXX"

The installer then writes it into config/sites/<id>/settings.yaml for you. Leave it empty and the script says so and moves on; you enter the key in the backend afterwards.

2. What the script does

In order — worth reading once, because two steps are destructive:

1. Finds DDEV. Homebrew's bin is only added to PATH by a login or interactive shell, so a run from a VSCode task or from cron would not see it. The script looks in /opt/homebrew/bin and /usr/local/bin itself.
2. Loads the environment file you picked.
3. Writes the project name into .ddev/config.yaml. This happens before anything is deleted, because ddev delete resolves the project through that file — the shipped name is the one this package was built from, not yours.
4. Deletes the existing DDEV project — ddev delete --omit-snapshot -y — but only if RESET_DB=1. The shipped .env has RESET_DB=1.
5. Starts DDEV after creating public/, which must exist before ddev start or DDEV warns about a misconfigured docroot.
6. Writes back PROJECT_NAME, SITE_IDENTIFIER, PROJECT_TITLE, INSTALL_DEMO and the resolved DDEV_BASE into the environment file.
7. ddev composer install — this is where packages/yavi-core and packages/yavi-lucerne are linked into vendor/ through the path repository.
8. Starts DDEV a second time. DDEV writes config/system/additional.php — database connection, ImageMagick paths, mail transport and trustedHostsPattern — but only once it recognises the project as TYPO3, which it does by looking for vendor/typo3. At step 5 that did not exist yet. Without this the site answers every request with "The current host header value does not match the configured trusted hosts pattern".
9. Installs TYPO3 with typo3 setup, unless config/system/settings.php already exists.
10. Imports .tarballs/yavi-demo.sql.gz — only when you asked for the demo, and only when the pages table is empty. An existing site is never overwritten by this step.
11. extension:setup activates both extensions.
12. Applies init-settings.php if the project ships one. It has to run
13. after extension:setup, which writes the ext_conf_template.txt defaults and would otherwise overwrite these values.
14. Sets up config/sites/<id>/ — renames the one shipped configuration to your site identifier, or copies it from a package's Initialisation/Site/. If several packages ship one, it asks which.
15. Writes the licence key from LICENCE_KEY into config/sites/<id>/settings.yaml. Shipped site configurations carry an empty key so that no key is ever distributed — see below.
16. Sets up the base structure — only when you installed without the demo. Creates a root page, imports .tarballs/yavi-static-elements.t3d below it and rewrites the five settings that address those records by uid, because the import assigns new ones. Then flushes the cache, since the settings are written after the TypoScript constants were built.
17. Copies additional.php from a package's Initialisation/System/, but never over an existing one.
18. Copies Initialisation/Files of every package into public/fileadmin/ — again only when you asked for the demo, since nothing would reference those files otherwise.
19. Deletes all backend users and groups, then creates the admin you were asked for.
20. Flushes the caches and prints the URLs.

When it is done, it prints where everything is:

==> Done
Frontend: https://yavilucerne.ddev.site
Backend:  https://yavilucerne.ddev.site/typo3
Site ID:  yavilucerne
User:     admin
Demo:     installed

3. What the demo content gives you

This path installs with demo content. It arrives in two halves, and both are needed — the database holds the records, the media folder holds the files those records point at:

The result is a complete standard site — 60 pages with navigation and a mega menu, a hero carousel, and every content element type in real use. Together with the theme settings in config/sites/<id>/settings.yaml that is the whole setup: nothing else has to be configured before the site renders like the demo.

The media are sorted by subject under fileadmin/dummy-media/: hero/, team/, casestudy/, services/, gallery/, header/, audio/, video/, documentation/, downloads/, plus yavi-icons/ and yavi-logos/ as icon and placeholder-logo libraries you can draw on for your own pages.

The database import is conditional: step 10 only runs when the pages table is empty, so a second run of the script never overwrites content you have already created.

Installing without the demo

Answer n at Install the demo site, or set INSTALL_DEMO=0 in the environment file before the run. The demo dump and the demo media are then skipped — but you do not end up with a blank installation.

The theme renders its frame from content records: the topbar, the sticky bar and the five footer columns are all content elements, not settings. An installation that only skipped the demo would therefore show a site with no header bar and an empty footer, and there would be nothing to click on to find out why.

So the installer sets up a starting point instead:

==> Setting up base structure (no demo)
    Created root page 'Home' (uid 1)
    Imported static elements below uid 1
    page.footer.pid: 4
    page.stickybar: 16
    page.topbar: 15
    page.socialtopbar: 13
    page.theme.footernavigation.navigationValue: 5

Twelve pages and sixteen content elements in total. Their URLs are flat — /imprint, /privacy-policy, /contact — the folders they sit in do not appear in the path.

The six legal pages carry their titles and page header only. The text is deliberately not shipped: legal wording belongs to your company, not to the theme vendor, and boilerplate that reads plausibly is worse than an empty page you still have to fill. The contact block in the footer works the same way — it shows Your Company, 2978 Cedar Lane and info@example.com as placeholders.

Everything else in the tree is yours to build. What the demo would have shown — carousels, card layouts, the element gallery — is not part of this; if you want to look at it, install with the demo once in a second project and compare.

How the wiring survives the import

Those five settings address content by uid, and an import assigns new numbers. The installer therefore looks up what it just imported and rewrites the settings to match. That is why page.footer.pid reads 4 in the output above and not the 62 it has in the demo — the same structure, different numbers.

If you ever move the footer page or rebuild it yourself, that setting is where you point the theme at the new one: Yavi Theme → Config → Footer Content Page.

Why the media exist twice

Step 17 copies Initialisation/Files/ flat into public/fileadmin/, which is where the dump's sys_file records point (fileadmin/dummy-media/…). TYPO3 itself copies the same folder to fileadmin/<extension_key>/ when the extension is activated — for Lucerne that is a second, unused 24 MB under fileadmin/yavi_lucerne/. Deleting it is safe; it is remembered in sys_registry and comes back only on a fresh install.

4. The licence key

Put it in the environment file before the run and step 14 fills it in for you:

LICENCE_KEY="XXXX-XXXX-XXXX-XXXX"

Leave it empty and the script says so and moves on; you then enter the key in the backend, under Yavi Theme → Licence. Either way the key is required — without a valid licence the extension does not work; see 11 — Licence.

5. Verify

ddev exec vendor/bin/typo3 extension:list | grep yavi

yavi_core and yavi_lucerne, both active. In the backend a Yavi Theme entry appears in the module menu below Site Management, with five pages: Design / Colors, Layout, Custom CSS, Config, Licence.

If the module is missing, either the extension is not active or the backend user is not an administrator — the module is admin-only by design.

If the run stops at "ddev-router failed to become ready"

Failed to start yavilucerne: ddev-router failed to become ready after 60.0s

This is DDEV, not the package. The router serves every DDEV project on the machine at once, and it has sixty seconds to load all their routes. With several projects running it can miss that window — it usually finishes a moment later, but the installer has already stopped by then.

ddev poweroff
./init-yavi.sh

ddev poweroff stops every project and removes the router container, so it comes back up with only the routes of the project you are starting. Running the installer again is safe: with RESET_DB=1 it starts over, and nothing had been installed at the point where it stopped.

If it happens again, the router itself is stale:

ddev poweroff
docker rm -f ddev-router
ddev start

6. Continue

The site is installed, but the theme only takes effect once its Set is active and the licence is entered. Continue with 05 — Setting up the first site.

Updating

Updates come through the same customer portal: **licence.yavithemes.com → Konto → Downloads**. The page lists each licence with its Updates until date. The site keeps running when that date passes — an expired update window blocks new versions, not the installation you already have.

Only yavi-core is updated. The theme extension is yours: you edit its SCSS, its templates and its settings, and an update must not overwrite that work. That is why the portal offers the framework on its own, as Framework update, next to the full package:

Once your update window has ended, the Framework update button keeps offering the last version released inside it. The full package is refused from that day on, because only its current build exists.

Back up first — by the time you update, the installation is no longer disposable, and the database migrations an update runs are not reversible by restoring the old files:

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

An update then replaces one folder and nothing else:

rm -rf packages/yavi-core
unzip yavi-core-<version>.zip -d /tmp/yavi-update
cp -R /tmp/yavi-update/yavi-core packages/

ddev composer dump-autoload
ddev exec vendor/bin/typo3 extension:setup
ddev exec vendor/bin/typo3 cache:flush

packages/yavi-lucerne stays where it is. If you want the theme's newer templates as well — because you have not changed them, or want to merge — take that folder from the full package and compare before you overwrite.

Letting Composer do it

The same archive is also served by a licensed Composer repository, so you can skip the manual copying. Set it up once:

ddev composer config repositories.yavi composer https://repo.yavithemes.com
ddev composer config --auth http-basic.repo.yavithemes.com licence YOUR-LICENCE-KEY
ddev composer require webagentur-yahya/yavi-core:^1.0

From then on an update is one command:

ddev composer update webagentur-yahya/yavi-core
ddev exec vendor/bin/typo3 extension:setup
ddev exec vendor/bin/typo3 cache:flush

Three things worth knowing:

• The licence key is the password, the user name can be anything. It lands in auth.json next to your composer.json — that file belongs in .gitignore. On a server or in a pipeline use the environment variable instead: COMPOSER_AUTH='{"http-basic":{"repo.yavithemes.com":{"username":"licence","password":"YOUR-LICENCE-KEY"}}}'.
• The repository only ever offers versions released inside your update window. After it ends, composer update finds nothing new instead of failing.
• packages/yavi-core stays in the project as the offline copy the ZIP shipped. Composer now takes the framework from vendor/ and ignores that folder.

The theme is deliberately not part of this. It stays a local path package, so no composer update can ever touch your changes to it.

Do not re-run init-yavi.sh to update. It would delete the database and every backend user.

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

Removing

ddev composer remove webagentur-yahya/yavi-lucerne
ddev exec vendor/bin/typo3 cache:flush

Content records stay in the database. Their content element types no longer exist, so the page module shows them as unknown types — they are not deleted, and reinstalling brings them back intact.