LAMP (Apache/mod_php)¶

The LAMP role starts a managed instance of Apache with php-fpm that can be used to easily run a production-ready PHP application server.

Note

The Apache configured by this role does not bind / open firewall ports to the frontend network automatically. It is not intended to serve applications directly to consumers but should be placed behind a webgateway.

Configuration¶

This role is configured exclusively using NixOS configuration options. It can provide multiple applications by setting up multiple vhosts and you can put the configuration in a single file or distribute it over multiple files depending on your use case.

As a service user, place a file in /etc/local/nixos/myservice.nix:

A complete configuration might looks something like this:

{ pkgs, ... }:

{

  flyingcircus.roles.lamp = {

    vhosts = [
      { port = 8000;
        docroot = "/srv/s-myserviceuser/application.git/docroot";
      }
      { port = 8001;
        docroot = "/srv/s-myserviceuser/application.git/other_php_version_root";
        pool = {
            phpPackage = pkgs.lamp_php80;
            settings = {
                "pm.max_requests" = 50;
            };
        };
        apacheExtraConfig = ''
          FancyIndexing on
        '';
      }
    ];

    php = pkgs.lamp_php74;

    apache_conf = ''
      MaxRequestWorkers 5
    '';

    fpmMaxChildren = 100;

    php_ini = ''
      ; max filesize
      upload_max_filesize = 200M
      post_max_size = 200M


      date.timezone = Europe/Berlin

      session.save_handler = redis
      session.save_path = "tcp://myservice01:6379?auth=<secret>"
    '';

  };
}

`flyingcircus.roles.lamp.vhost` (required)¶

The vhost configuration allows you to configure multiple applications per VM each running on a separate port. The two options for every vhost thus are:

port: The port number that Apache should listen on for this application. We recommend starting with 8000 and counting up from there.
docroot: The absolute path to the docroot of your application.
apacheExtraConfig: Additional text appended to virtualhost section of apache config.

In general, the apache configuration is generated by the role like this:

Listen *:${port}
<VirtualHost *:${port}>
    [...]
    ${vhost.apacheExtraConfig}
</VirtualHost>

pool: Described below

`flyingcircus.roles.lamp.vhost.*.pool` (optional)¶

Allows you to configure the phpfpm pool for this vhost individually.

Options are:

user

User account under which this pool runs.

settings

PHP-FPM pool directives. Refer to the “List of pool directives” section of the PHP Manual for details. Note that settings names must be enclosed in quotes (e.g. "pm.max_children" instead of pm.max_children). This overrides the default options set by our role.

Example:

{
        "pm" = "dynamic";
        "pm.max_children" = 75;
        "pm.start_servers" = 10;
        "pm.min_spare_servers" = 5;
        "pm.max_spare_servers" = 20;
        "pm.max_requests" = 500;
}

phpPackage

The PHP package to use for running this PHP-FPM pool. This overrides the option set by the role.

See previous option for example.

phpOptions

Options appended to the PHP configuration file php.ini used for this PHP-FPM pool.

phpEnv

Environment variables used for this PHP-FPM pool.

Example:

{
        HOSTNAME = "$HOSTNAME";
        TMP = "/tmp";
        TMPDIR = "/tmp";
        TEMP = "/tmp";
}

group

Group account under which this pool runs.

extraConfig

Extra lines that go into the pool configuration. See the documentation on php-fpm.conf for details on configuration directives.

`flyingcircus.roles.lamp.apache_conf` (optional)¶

Any text written here will be included in the global Apache configuration. Use this to adjust global settings like workers:

MaxRequestWorkers 5

Note, that if you distribute your configuration over multiple files then you can repeat this option and the values will be concatenated to a single big Apache config file. They will also always apply to all vhosts.

`flyingcircus.roles.lamp.fpmMaxChildren` (optional)¶

Set the maximum number of worker processes any vhost is allowed to spawn.

`flyingcircus.roles.lamp.php` (optional)¶

A reference to a PHP package that will be used in Apache and in the CLI.

Supported packages:

pkgs.lamp_php72 (outdated but provided for legacy applications)
pkgs.lamp_php73
pkgs.lamp_php74
pkgs.lamp_php80
pkgs.lamp_php81
pkgs.lamp_php82

The lamp_php_* packages provided by our platform include commonly used PHP extensions, currently:

bcmath
imagick
redis
memcached

There are more pre-packaged extension that can be added via Nix code. For example, to add the apcu extension along with the ones provided by lamp_php80, use:

php = pkgs.lamp_php80.withExtensions ({ enabled, all }:
  enabled ++ [
    all.apcu
  ]);

You can also use any custom PHP package from the NixOS universe (if you know what you are doing. ;) )

For more information about PHP packaging on Nix, refer to the PHP section of the Nixpkgs manual.

`flyingcircus.roles.lamp.tideways_api_key` (optional)¶

If you have an account with tideways.com then you can quickly enable the tideways profiler for your application by setting the API key here:

flyingcircus.roles.lamp.tideways_api_key = "my-api-key";

`flyingcircus.roles.lamp.php_ini` (optional)¶

We deliver a production-tested PHP configuration that you can extend by placing additional configuration instructions in this option:

; max filesize
upload_max_filesize = 200M
post_max_size = 200M

Similar to the flyingcircus.roles.lamp.apache_conf option this will be concatenated with from all Nix configuration files with our global platform settings and will be applied to all vhosts.

PHP version and modules¶

We currently provide a single pre-selected version of PHP (7.3) with a fixed set of modules. Please contact our support if you need a different version of PHP and/or further modules.

Interaction¶

No special interaction is required. Changes to the configuration need to be activated as usual using:

$ sudo fc-manage -b

Network¶

The Apache server listens on the srv interface only.

Security¶

Apache runs in a separate user who is a member of the service group and thus can (by default) access files owned by service users.
Access is read-only for Apache by default, but you can grant write access for directories by running :command:chmod g+rwsx on the directory.

Debugging¶

To assist with debugging we have integrated the Tideways application performance monitoring daemon and PHP module by default.

To enable it, you just have to place your Tideways API key in /etc/local/lamp/php.ini:

$ echo "tideways.api_key=<secretapikey>" >> /etc/local/lamp/php.ini
$ sudo fc-manage -b

Logging¶

Apache logs are available in /var/log/httpd.

PHP output is accessible through the journal, running journalctl -t php -t httpd.

Monitoring¶

Our platform monitoring checks that Apache is running (through systemd) and verifies that the Apache statuspage (mod_status accessible via curl http://localhost:8001/server-status) is available.