English

Русский
Deutsch

English

Русский
Deutsch

Appearance

Nginx. Virtual hosts in expert mode ​

This article continues Nginx. Working with virtual hosts. If you are setting up your first site, start there: creating a host in builder mode covers most cases. Come here when you need directives that the form does not expose: a custom try_files, proxying, specific FastCGI parameters, rate limiting. Below: how to open expert mode, how to switch between modes without losing settings, the starter template explained, and how to wire up PHP-FPM by hand.

When you need expert mode ​

Expert mode is for the cases the standard form cannot cover. Typical examples:

  • a custom try_files — for example, an SPA with try_files $uri $uri/ /index.html; or WordPress with try_files $uri $uri/ /index.php?$args;;
  • non-standard access_log / error_log — a custom format, path, or disabled logs;
  • proxy_pass to an upstream service with fine-grained header and timeout tuning;
  • extra fastcgi_param directives on top of the standard PHP-FPM block;
  • rate limiting, caching, gzip tuning;
  • if, map, set directives.

For typical sites — static content, WordPress on a stock stack, a basic reverse proxy — expert mode is not needed. Use builder mode.

Opening expert mode ​

  1. In the side menu of the Nginx section click «Create virtual host».
  2. The creation page opens in builder mode. In the bottom panel click «Switch to expert mode».
  3. The «Switch to expert mode» dialog appears. Click «Proceed».
  4. A raw config editor opens with syntax highlighting and a starter template.
  5. Fill in the «Domain name» field above the editor — this is the virtual host name under which the panel stores the configuration. Adapt the template to your site.
  6. Click «Create».

⚠️ Switching modes on the creation page

To switch back to builder, use the «Switch to bulder mode» button in the same bottom panel. On the creation page it works like this:

  • The first switch to expert opens the starter template (see below).
  • Switching back to builder restores the form fields — values entered in builder are preserved.
  • Switching to expert again does not preserve the intermediate draft and overwrites it with the same starter template.

If you edited the raw config in expert, switched to builder, and came back — your edits are lost. Save the config with «Create» before switching, or copy the text into an external editor.

Starter template ​

nginx
# This configuration file is automatically generated by BeAdmin.
# You can modify it according to your needs.

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }


    access_log /var/log/nginx/example.access.log;
    error_log  /var/log/nginx/example.error.log;
}

What each directive does:

  • listen 80; — port. For HTTPS change it to 443 ssl; and add ssl_certificate and ssl_certificate_key. In expert mode the panel does not issue the certificate automatically when the host is saved — issue it manually after creation, as described in Issuing an SSL certificate.
  • server_name example.com www.example.com; — domains the block answers on. Linked to the «Domain name» field above the editor (see below).
  • root /var/www/example.com/public; — the site files root. Replace example.com with your own domain. The directory must exist and be readable by the nginx user, otherwise the site responds with 403 or 500.
  • index index.php index.html; — default files for a directory request. Order matters: for a PHP site list index.php first.
  • location / { try_files $uri $uri/ =404; } — the standard pattern: look up the exact path, then the directory, otherwise 404. For an SPA replace =404 with /index.html. For WordPress — with /index.php?$args.
  • access_log and error_log — log paths. It is convenient to keep them at /var/log/nginx/<domain>.access.log and /var/log/nginx/<domain>.error.log — that is how the logs shown by the Nginx module in the panel are wired.

⚠️ Domain substitution into server_name

When the «Domain name» field becomes non-empty for the first time after the editor is opened on the creation page, the panel substitutes <domain> www.<domain> into the server_name of the starter template once — for example, example.com www.example.com. After that the «Domain name» field and the server_name line are not synchronised: manage server_name manually in the editor. On an existing host page the substitution does not run.

⚠️ server_name validation on save

When you click «Create» the panel checks that every value in server_name ends with what is entered in the «Domain name» field. If the field is example.com, then example.com, www.example.com, api.example.com are valid, while api.other.com is not — and the host cannot be saved.

Wiring PHP through PHP-FPM ​

The starter template does not enable PHP: index.php is listed in the index directive, but without a .php handler the server returns the source as plain text. To run PHP scripts the site needs a location ~ \.php$ { ... } block that forwards requests to a PHP-FPM socket.

The PHP module in BeAdmin supports several versions in parallel. Each one creates its own socket at /var/run/php/php<version>-fpm.sock — for example, php8.3-fpm.sock. Look up the version for a given site in the PHP module and put it into fastcgi_pass.

In the standard install via BeAdmin, Nginx comes from the official nginx.org repository. The /etc/nginx/snippets/fastcgi-php.conf snippet is not shipped there — it ships only with the nginx-full and nginx-extras packages from the native Debian and Ubuntu repositories. The recommended approach is therefore to spell out the FastCGI parameters explicitly:

nginx
location ~ \.php$ {
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
}

If the server runs Nginx from the distribution packages and the snippet is present, you can include it directly:

nginx
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
}

Saving and applying ​

After you click «Create»:

  • BeAdmin saves the config and activates the virtual host.
  • If the site files are already in the root directory, the site is available immediately.
  • Before activation the panel checks the config with nginx -t. If there is a syntax error or an unknown directive, the host is not created — a notification appears in the corner: «Failed to create the virtual host due to a configuration error. More details are available in the logs.» Look up the exact nginx -t error lines in the system logs of the Nginx module, fix the config, and click «Create» again.

Managing an existing host ​

  • To open the raw config of an existing host, on its page click «Switch to expert mode» in the bottom panel. To go back, click «Switch to bulder mode».
  • The configs of the two modes are stored differently: the builder config is a structured set of form fields in the panel database, the expert config is a raw file on disk. When switching from expert to builder the panel saves the current raw file in an internal backup, and builder shows its own last saved set of fields.
  • The panel does not remember an intermediate draft in expert mode: every return to expert pulls the current config from the server. If you edited the raw config, switched to builder, and came back without clicking «Save», the edits are lost — the editor opens the latest version saved on the server.
  • A host can be deleted from the side menu via the trash icon next to its name. The virtual host configuration file and its logs are removed; the site files in the root directory and the SSL certificates remain on the server.

See also ​

BeAdmin © 2025. All rights reserved.