Skip to content

HomeCoreTutorials

Host PHP application

In this tutorial, you will set up a basic PHP application using the Cyberfusion Core CLI. At the end of this tutorial, a PHP application runs on a cluster, with a MariaDB database.

To follow this tutorial, you must have basic knowledge of application hosting - such as FPM pools and SSL certificates.

Prerequisites

The Cyberfusion Core CLI (corectl) is installed and set up.

Unsure about the parameters that a command takes? Run corectl <command> --help. You see all subcommands, descriptions and possible parameters.

Result

In this tutorial, you will set up a cluster, and add nodes to it.

The diagram below shows the basic setup of your cluster.

graph TD
    subgraph Cluster["Cluster"]
        subgraph AdminNode["Node (admin)"]
            B["SSH"]:::node
        end
        subgraph ApplicationNode["Node (application)"]
            C["nginx, PHP, MariaDB"]:::node
        end
    end

Create cluster

The PHP application and database exist on a cluster. A cluster consists of nodes, each having one or more tasks (groups). This is explained further when creating a node.

Determine site

First, determine the site (geographical location) in which the cluster runs.

List all sites:

corectl sites list

Note the name. It is used in the next step.

Create cluster

Create a cluster on which you can host PHP applications and databases:

corectl clusters create --group Web --group Database --site-name <site_name> --description "My test cluster" --php-version 8.3 --mariadb-version 10.11 --mariadb-cluster-name "test" --mariadb-backup-interval 12 --mariadb-backup-local-retention 7 --with-database-toolkit --unix-users-home-directory /home

Replace <site_name> by the site name (from the step 'Determine site').

All parameters used in the command explained:

Parameter Description
--group Cluster groups. These determine what can be hosted on the cluster. To run applications and databases on it, add both groups.
--site-name Name of the site (geographical location).
--description
--php-version
--mariadb-version
--mariadb-cluster-name MariaDB cluster name. Only used internally.
--mariadb-backup-interval How often database backups are created (in hours).
--mariadb-backup-local-retention Amount of backups to keep.
--with-database-toolkit Manage databases through the Cyberfusion Core API.
--unix-users-home-directory The directory in which UNIX user home directories are stored.

View cluster

List all clusters to see the new cluster:

corectl clusters list

Note the cluster name. You'll pass it in successive commands.

Add cluster nodes

A cluster contains nodes. A node contains one or more groups, such as PHP or MariaDB.

Determine product

A node has a product. The product determines the size (CPU, RAM, disk). The right product depends on your application.

List all products:

corectl nodes products-list

Note the product name. It is used in the next step.

Create admin node

First, create the so-called admin node. You log in to this node with SSH or SFTP. It is also possible to run other administrative tasks on this node, such as crons.

Create the node:

corectl nodes create S <cluster_name> --group Admin --group PHP

ℹ️ S refers to the product. The product determines the size (CPU, RAM, disk). Using the admin node for SSH or SFTP only? Then S usually suffices, as not many resources are required. You can upgrade the product later.

List all nodes to see the new node:

corectl nodes list

Create nginx + PHP + MariaDB node

Second, create the node that hosts the application (web server and PHP-FPM) and MariaDB database.

Create the node:

corectl nodes create S <cluster_name> --group nginx --group PHP --group MariaDB

List all nodes to see the new node:

corectl nodes list

Add UNIX user

The PHP application runs under a UNIX user.

Create the UNIX user:

corectl unix-users create <username> <cluster_name>

Replace <username> by the username. It is used for your own administration. It may contain the characters a-z, 0-9, - and _. For example: dropflix or dropflix_website.

Replace cluster_name by the cluster name (from the 'Create cluster' step).

Add SSH key

By adding an SSH key, you can log in to the UNIX user with SSH.

Add the SSH key:

In the command below, the <key_name> is the name under which the key will be saved on the cluster. The <username> refers to the username of the UNIX user we've created in the previous paragraph.

corectl ssh-keys create-public-keys <key_name> ~/.ssh/id_ed25519.pub <unix_user_username>

Replace key_name by the SSH key name. It is used for your own administration. It may contain the characters a-z, A-Z, 0-9, - and _.

Replace unix_user_username by the UNIX user username (from the step 'Add UNIX user').

⚠️ Only SSH keys with the following types are allowed: rsa, ed25519

Configure firewall

By default, SSH is not accessible. Make it accessible from specific IP addresses.

Create firewall group

A firewall group holds several IP addresses/networks. You use it in the next step.

Create the firewall group:

corectl firewall-groups create <name> <ip_address> <cluster_name>

Replace <name> by the name. It is used for your own administration. It may contain the characters a-z. 0-9 and _. For example: 4g_connection or office.

Replace ip_address by your IP address. Don't know your IP address? Look it up on https://cyberfusion.io/ip-checker. Have multiple IP addresses? Specify them one after another. For example: 203.0.113.1 2001:db8::1.

Replace cluster_name by the cluster name (from the 'Create cluster' step).

ℹ️ It is also possible to specify IP networks with a CIDR. For example: 203.0.113.0/24.

Create firewall rule

A firewall rule allows access from a specific source (in our case: firewall group) to a specific destination (in our case: SSH on the admin node).

Create the firewall group:

corectl firewall-rules create <admin_node_hostname> --service-name SSH --firewall-group-name <firewall_group_name>

Replace admin_node_hostname by the admin node hostname (from the step 'Create admin node'). Don't know what it is? List all nodes using corectl nodes list. In the output, look up the node with the Admin group, and copy the value in the Hostname column.

Replace firewall_group_name by the firewall group name (from the step 'Create firewall group').

Log in with SSH

You can log in to the UNIX user over SSH - using the SSH key that you added:

ssh <unix_user_username>@<admin_node_hostname>

Replace unix_user_username by the UNIX user username (from the step 'Add UNIX user').

Replace admin_node_hostname by the admin node hostname.

Create database

Create the database, user and grant. This command creates a database, and a user that can access it.

corectl databases create-all <database_name> <user_name> MariaDB <cluster_name>

Replace database_name by the database name. It may contain the characters a-z, 0-9, - and _. For example: dropflix or dropflix_website.

Replace user_name by the username. It may contain the characters a-z, 0-9, - and _. For example: dropflix or dropflix_website.

Replace cluster_name by the cluster name (from the 'Create cluster' step).

ℹ️ The database name and username may be identical. In most circumstances, there is no reason to differentiate between them.

Create FPM pool

An FPM pool (also known as PHP-FPM pool) runs PHP scripts for HTTP requests.

Create the FPM pool:

corectl fpm-pools create <name> <php_version> <max_children> <unix_user_username>

Replace name by the name. It may contain the characters a-z, 0-9, - and _. For example: dropflix or dropflix_website.

Replace php_version by the PHP version. The PHP version must be installed on the cluster. You specified it in the 'Create cluster' step (--php-version argument).

Replace max_children by the max amount of PHP processes that may run simultaneously. The correct value depends on 1) the amount of simultaneous requests to your application and 2) the speed of your application.

ℹ️ Don't know what to set max_children to? For small applications, 5 is usually a safe value. 25 for larger applications. You can change the value later using the corectl fpm-pools update-max-children command.

Create virtual host

A virtual host is the web space for specific domain(s).

Create the virtual host:

corectl virtual-hosts create-fpm-pool <domain> <unix_user_username> <fpm_pool_name>

Replace domain by the domain of your application. For example: dropflix.io. The corresponding www. domain is automatically added.

Replace unix_user_username by the UNIX user username (from the step 'Add UNIX user').

Replace fpm_pool_name by the FPM pool name (from the step 'Create FPM pool').

ℹ️ Want to add multiple domains to the same virtual host? Use corectl virtual-hosts add-server-alias. This is often used for multi-tenant applications.

Set DNS

List the IP addresses:

corectl clusters list-ip-addresses <cluster_name>

Replace cluster_name by the cluster name (from the 'Create cluster' step).

Point the domain of your application (from the step 'Create virtual host') to the IP addresses for which 'Service Account Group' is set to 'Load Balancer'.

Request Let's Encrypt certificate

Automatically protect your domain with HTTPS using Let's Encrypt.

First, create a certificate manager. This object holds information about the request that Cyberfusion does at Let's Encrypt on your behalf:

corectl certificate-managers create <domain_name> <www_domain_name> <cluster_name>

Replace domain_name by the domain of your application (from the step 'Create virtual host'). For example: dropflix.io.

Replace www_domain_name by the www domain of your application (from the step 'Create virtual host'). For example: www.dropflix.io.

Replace cluster_name by the cluster name (from the 'Create cluster' step).

Then, request the certificate manager at Let's Encrypt:

corectl certificate-managers request <domain_name>

Replace domain_name by the domain of your application (from the step 'Create virtual host'). For example: dropflix.io.

ℹ️ Just set DNS, and getting an error? Try again in an hour. The DNS may still be propagating.

Deploy PHP application

To deploy your PHP application, there are two options:

  • Upload files manually using SSH or SFTP.
  • Deploy the application using Git.

Want to deploy using Git? Add another SSH key for your pipeline using the instructions under 'Add SSH key'. Then, deploy your application in CI using rsync.