Operating System Ubuntu

How to Set Up a Yii Application on Ubuntu 26.04 LTS

Create a Yii3 project from the official application template on Ubuntu 26.04 LTS and serve it with Nginx and PHP-FPM.

This guide creates a new Yii application from the official yiisoft/app template on Ubuntu 26.04 LTS, checks it with the built-in development server and then serves it with Nginx and PHP-FPM. The same steps work on Ubuntu 24.04 LTS; the differences are listed where they matter.

The current generation of the framework is Yii3, released on 31 December 2025, and it needs PHP 8.2 or newer. Older tutorials download a Yii 1.1 archive and generate a site with yiic webapp. Do not start new work that way: according to the Yii release cycle, Yii 1.1 stopped receiving features in 2015 and reaches end of life on 31 December 2026, and Yii 2.0 is now in its security-fixes-only phase.

Requirements

  • A server running Ubuntu 26.04 LTS (or 24.04 LTS) and a non-root user with sudo; the examples use deploy.
  • A domain name pointing at the server, shown here as example.com.
  • PHP 8.2 to 8.5. Ubuntu 26.04 ships PHP 8.5 and Ubuntu 24.04 ships PHP 8.3, so the distribution packages are enough on both.

Install Nginx, PHP and Composer

Install the web server, PHP-FPM, the command-line PHP binary, a few common extensions and Composer from the Ubuntu repositories:

sudo apt update
sudo apt install nginx php-fpm php-cli php-mbstring php-xml php-curl php-intl unzip composer

Check the versions you received:

php -v
composer --version

Create the project

Create a directory that your own user owns, then let Composer download the application template and its dependencies into it. Run Composer as your normal user, not as root.

sudo mkdir -p /var/www/myproject
sudo chown deploy:deploy /var/www/myproject
cd /var/www
composer create-project yiisoft/app myproject
cd myproject

The directories you will touch most often are:

  • public/ – the only directory the web server may expose; it contains the entry script index.php.
  • src/ – your application code.
  • config/ – configuration, including per-environment settings for dev, test and prod.
  • runtime/ – files generated while the application runs.
  • yii – the console entry point.

Test with the built-in server

For a quick check, copy the example environment file and start the development server that ships with the template:

cp .env.example .env
./yii serve

The command prints the address it listens on, normally http://localhost:8080; add --port=8888 to use another port. Because it listens on the server itself, open an SSH tunnel from your workstation and browse to http://localhost:8080 there:

ssh -L 8080:localhost:8080 deploy@203.0.113.10

You should see the template's start page. Stop the server with Ctrl+C. The .env file sets APP_ENV=dev and APP_DEBUG=true and is meant for local development only; in production the environment is set by the web server, so remove the file again:

rm .env

Serve the application with Nginx and PHP-FPM

PHP-FPM runs as www-data, which needs to write to the runtime directory and to public/assets, where published asset files are placed:

sudo chgrp -R www-data /var/www/myproject/runtime
sudo chmod -R g+rwX /var/www/myproject/runtime

Create the server block. It follows the configuration from the Yii documentation: the document root is public/, every request that is not a real file goes to index.php, and the environment is passed to PHP as FastCGI parameters.

sudo nano /etc/nginx/sites-available/myproject
server {
    listen 80;
    listen [::]:80;
    server_name example.com;

    charset utf-8;
    client_max_body_size 128M;

    root  /var/www/myproject/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ ^/assets/.*\.php$ {
        deny all;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param APP_ENV "prod";
        fastcgi_param APP_DEBUG "false";
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        try_files $uri =404;
    }

    location ~* /\. {
        deny all;
    }
}

On Ubuntu 24.04 the socket is /run/php/php8.3-fpm.sock. Enable the site, test the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Send application logs somewhere

Yii3 application templates write their logs to standard output and do not create log files. PHP-FPM discards worker output unless you tell it otherwise, so enable output capture in the pool configuration. Open /etc/php/8.5/fpm/pool.d/www.conf (8.3 on Ubuntu 24.04) and set:

catch_workers_output = yes

Reload PHP-FPM. Application messages then appear in the PHP-FPM error log under /var/log.

sudo systemctl reload php8.5-fpm

Verify

Request the site from the server and from your browser:

curl -I http://example.com/

A 200 response and the start page in the browser mean Nginx, PHP-FPM and the application are wired together. If you get a 502, the socket path in fastcgi_pass does not match the installed PHP version; list /run/php/ to see the real name. A blank page or a 500 usually points at a permissions problem in runtime/ or public/assets; the PHP-FPM log shows the cause once output capture is enabled.

Next steps and maintenance

  • Put the site behind HTTPS before it goes public. When TLS is terminated by Nginx, the Yii documentation recommends adding fastcgi_param HTTPS on; to the PHP location so the application detects secure connections.
  • Run console commands with the same environment as the web server, for example APP_ENV=prod ./yii list.
  • Update dependencies with composer update in a development copy, commit composer.lock, and run composer install --no-dev on the server when you deploy.

The official guide continues from here with routing, views and databases: Yii3 definitive guide. Support dates for every branch are listed on the Yii release cycle page.

Frequently asked questions

Can I still run an existing Yii 1.1 or Yii 2 application?

It will run, but plan the migration. The release cycle page lists 31 December 2026 as the end of life for Yii 1.1, and Yii 2.0.50 and later receive security fixes only until their own end-of-life date in November 2027. Yii 1.1 was also written for much older PHP versions than the 8.5 that Ubuntu 26.04 ships.

Can I use Apache instead of Nginx?

Yes. The rule is the same for any web server: point the document root at the public directory and forward requests for non-existent files to index.php. The Yii cookbook has a dedicated Apache page next to the Nginx one.

Does the template support Docker?

Yes. The project ships a docker/ directory and a Makefile; make up starts the development stack and make help lists the other targets. The README asks for Docker Compose 2.24 or newer.

Why is there no log file in the runtime directory?

By default the template logs to standard output, which suits containers. On a classic server you either capture PHP-FPM worker output as shown above or configure a file log target in the application, which the Yii logging guide describes.

Share story:

Continue reading other guides on How VPS.