Skip to content
V
For developers
Architecture, conventions, the core and security
Getting started / Installation and setup

Installation and running#

Requirements#

What Version / note
PHP ≥ 8.3 (composer.json)
MySQL / MariaDB
Composer
Node.js and npm for building the assets
Redis recommended, can be turned off
Elasticsearch optional — without it search falls back to SQL

Procedure: getting the project running for the first time#

  1. Dependencies
composer install
npm install
  1. Configuration — copy the template and fill in the real values:
cp config/Shared/local.neon.example config/Shared/local.neon
openssl rand -hex 32          # the JWT secret

local.neon holds the database credentials (mariadb.* — the single source of truth, used by Doctrine and by nette/database alike) and jwt.secret. It is included last in config/common.neon, so it overrides every placeholder.

  1. The database — the schema lives in docs/sql/. The system uses no migrations; the schema is maintained by hand-written idempotent scripts.

  2. Redis — on hosting without Redis, uncomment in local.neon:

redis:
    storage: false
    sessions: false
jwt:
    useRedis: false          # the deny-list goes into the DB (needs a cleanup cron)
ratelimit:
    useRedis: false
  1. Assets
npm run build:admin        # the administration

The front-end theme is built from its own folder — see Front-end themes.

  1. Write permissions — temp/, log/, var/ and the upload folders.

  2. Set the cron token in the administration (1/cronToken) before wiring up the crons — without it every task returns 403.

  3. The scheduled tasks per the Deployment checklist and Scheduled tasks.

local.neon does not belong in git

It holds the database password and the JWT secret. It is in .gitignore (/config/local.neon and /config/Shared/local.neon) — check that before you commit anything.

validateClass is not a migration

Validating an entity against the schema only tells you what does not match. The schema change itself has to be made by you, with a script in docs/sql/.

Procedure: turning debug mode on for a development machine#

touch config/debug-mode.flag      # gitignored, its existence = debug ON

Or through the NETTE_DEBUG=1 environment variable, which takes precedence. The production default is off; in detail Deployment checklist.

Debug mode is not configured in local.neon

It is decided in App\Bootstrap::resolveDebugMode(), that is, before the configuration is loaded. Nothing written into NEON has any effect on debug.

Configuration#

File Contents
config/common.neon the skeleton, includes the rest
config/Shared/*.neon shared configuration by area (25 files)
config/Shared/local.neon 🔴 secrets and local overrides, outside git
config/debug.neon what applies only in debug mode
config/Admin/, config/System/ per-section configuration

Part of the settings live in the database, not in files — read by SettingManager and at runtime by SettingContext.

SettingContext has two layers

setSettings() is a no-op for managers. In scripts you also have to write setServerSettings(), otherwise the settings do not reach where you expect them to.

Procedure: I changed the configuration and nothing happened#

  1. Delete temp/cache. Nette holds the compiled DI container.
  2. For a new language also temp/cache/translation/ — the translation catalogue does not regenerate itself.
  3. For a new class the stale class map may be the problem.
  4. Only then look for a bug in what you wrote.

A stale class map brings down the WHOLE site

Not with a comprehensible message — with a 500 on every page at once. After adding a language, a new module or changing the configuration, always delete temp/cache.

Verification after installation#

  1. The landing page.
  2. Signing in to the administration.
  3. One listing and one form in the administration.
  4. Submitting one form on the front end.
  5. log/ — did anything appear?

A live click-through reveals what a harness does not

A test run through the CLI bypasses plenty of layers. Before declaring anything done, click through it in a browser — in detail Tests and tooling.

Production and development share one database

An installation on a new machine therefore connects to live data. Before trying anything out, check which database you are actually connected to.

Where to look#

I want Where
the local configuration template config/Shared/local.neon.example
how debug mode is decided app/Bootstrap.php → resolveDebugMode()
the schema SQL scripts docs/sql/
the build commands package.json, composer.json
the deployment checklist Deployment checklist

Follow-up chapters: Deployment checklist · Scheduled tasks · Project structure · Tests and tooling