Deployment

Deployment is moving a site from the developer's computer to a server where visitors will see it. Besides copying files you have to switch off debug mode, point the web server at the right folder and update the database.

The mode

The mode is set by two constants at the start of web/index.php:

<?php
// web/index.php
 
defined('YII_DEBUG') or define('YII_DEBUG', false);
defined('YII_ENV') or define('YII_ENV', 'prod');

YII_DEBUG enables detailed error reports, YII_ENV names the environment: dev is development, prod is the production server. On the server a visitor sees an ordinary error page instead of a report with code, and the debug toolbar and Gii are off: in config/web.php they are attached inside the condition if (YII_ENV_DEV).

To avoid editing the file on every deployment, the values are read from the server's environment variables:

define('YII_DEBUG', getenv('YII_DEBUG') === 'true');
define('YII_ENV', getenv('YII_ENV') ?: 'prod');

If the variables are not set, the site runs in the safe prod mode.

The web root

The web server must serve the web folder, not the project folder. An example for nginx:

server {
    server_name example.com;
    root /var/www/blog/web;
    index index.php;
 
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
 
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }
}

The try_files line passes all requests that have no file to index.php, which is how pretty URLs work.

Deployment steps

git pull
composer install --no-dev --optimize-autoloader
php yii migrate --interactive=0
php yii cache/flush-all

Folder permissions

The web server must have write permission for two folders: runtime (logs, cache) and web/assets (Yii copies styles and scripts from asset bundles here). It only needs to read the other files.

Settings for the server

The database password and the mail server address are different on the server. They are read from environment variables:

// config/db.php
return [
    'class' => 'yii\db\Connection',
    'dsn' => getenv('DB_DSN'),
    'username' => getenv('DB_USER'),
    'password' => getenv('DB_PASSWORD'),
    'charset' => 'utf8mb4',
    'enableSchemaCache' => YII_ENV_PROD,
    'schemaCacheDuration' => 3600,
];

enableSchemaCache keeps the table structure in the cache: Yii stops asking the database for it on every access, and the site works noticeably faster. This cache is cleared after migrations, which is why the deployment steps include cache/flush-all.

Checking after deployment

• the home page opens and there is no debug toolbar at the bottom;
• the URL /gii answers with a 404 error;
• a non-existent URL shows your error page, not a report with code;
• there are no new errors in runtime/logs/app.log.

Common mistake

If the project folder, not web, is set as the web root, visitors can reach files such as /config/db.php and /runtime/logs/app.log with passwords and internal data. The web root is always the web folder.