Vanilla Ubuntu Installation

This guide takes you through all steps from getting a clean / vanilla server with Ubuntu 20.04 online to getting Apex fully installed and functioning.

Install Packages

First, install all necessary packages such as PHP 8.0, Nginx, redis, mySQL, and others. You may do this by running the following commands via SSH:

sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get -y update
sudo apt-get -y install redis libfreetype6-dev php8.1 php8.1-curl php8.1-mysql php8.1-xml php8.1-mbstring php8.1-zip php8.1-gd php8.1-redis git subversion nginx php8.1-fpm mysql-server unzip certbot
sudo curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Create mySQL Database

Next, create the necessary mySQL database. Connect to mySQL with the command:

sudo mysql

Once connected and at the mySQL prompt, run the following SQL statements:

mysql> CREATE DATABASE apex;
mysql> CREATE USER 'apex'@'localhost' IDENTIFIED BY 'your_password';
mysql> GRANT ALL PRIVILEGES ON apex.* TO 'apex'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> \q

Naturally, change the database password in the above statement to your desired password, and if desired feel free to change the database name and username as well.

Install Apex

Now install Apex itself with the following commands:

sudo rm -rf /var/www
sudo composer --no-dev create-project apex/apex /var/www
sudo cp /var/www/apex /usr/local/bin/ && sudo chmod 0755 /usr/local/bin/apex
sudo chown -R ubuntu:ubuntu /var/www
cd /var/www
apex --redis-local

This will start the Apex installer. Simply enter your domain name followed by mySQL information for the database you previously created, wait a few seconds and Apex will be fully installed. A few notes regarding the above commands:

  • In the fourth command above, change ubuntu:ubuntu to the appropriate user / group for your machine.
  • The --redis-local option specifies to use default redis connection information. If needed, omit this option and the installer will request the redis information.
  • If you prefer to use PostgreSQL or SQLite over mySQL, open the file at /boot/container.php and on approximately line 15 you will see an entry for DbInterface::class. Simply change this to either PostgreSQL or SQLite, and the installer will use that database engine instead.

Once done, you should install some base Apex packages with the command:

apex install webapp users
sudo chown -R www-data:www-data /var/www/storage

Add Crontab Job

If you didn't allow the installer to automatically add the crontab job, and wish to have necessary crontab jobs to automatically perform tasks at set time intervals, run the following command:

(crontab -l; echo "* * * * * /var/www/apex crontab > /dev/null 2>&1";) | crontab

Generate SSL Certificate via Lets Encrypt

This only applies if your domain name is already pointing to the server's IP address and you want SSL, which is naturally recommended. In the first step of this guide the certbot package was installed which is what will be used to generate a free SSL certificate via the popular Let's Encrypt service.

Ensure Nginx is not running and generate the SSL certificate with the following commands:

sudo /etc/init.d/nginx stop
sudo certbot certonly

You will be prompted with a question asking how you would like to perform the challenge. Enter 1 to spin up a temporary instance, and next enter your e-mail address and agree to the terms as the prompts will ask. You will then be asked for your domain name, which needs to be already pointing to this server's IP or else the challenge will fail.

The challenge will then be run to ensure the domain name is pointing to the server, and upon success your new SSL certificate will be generated and saved on the server.

Configure php-fpm

Make a small modification to the default php-fpm file. Open the default configuration file with the command:

sudo nano /etc/php/8.0/fpm/pool.d/www.conf

on Approximately line #36 you will see the following line:

listen = /run/php/php8.0-fpm.sock

Change this line to:

listen = 127.0.0.1:9000

Then press Ctrl+X followed by the "Y" and Enter keys to save the file.

Configure Nginx

Remove unnecessary config files, and open a default Nginx configuration file with the commands:

sudo rm -rf /etc/nginx/sites-enabled
sudo nano /etc/nginx/conf.d/http.conf

Modify lines 3, 9, 13 and 14 in the below file to your domain name, and paste the contents into terminal by pressing Ctrl+Shift+V. Then save and close the file by pressing Ctrl+X followed by the "Y" and Enter keys.

server { 
    listen 80;
    server_name domain.com www.domain.com;
    rewrite     ^   https://$server_name$request_uri? permanent; 
}

server {
    listen 443 ssl;
    server_name domain.com www.domain.com;
    root    /var/www/public;
    index index.php;

    ssl_certificate /etc/letsencrypt/live/domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/domain.com/privkey.pem;

    location / { 
        send_timeout 30;
        proxy_read_timeout 30;
        proxy_connect_timeout 30;
        try_files $uri $uri/ /index.php?$query_string; 
        gzip_static on;
    } 

    client_header_timeout   30; 
    client_body_timeout     30; 
    send_timeout            30; 

    location ~ \.php$ { 
        fastcgi_pass   127.0.0.1:9000; 
        fastcgi_index  index.php; 
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_connect_timeout 30s; 
        fastcgi_send_timeout 30s; 
        fastcgi_read_timeout 30s; 
        fastcgi_buffer_size 128k; 
        fastcgi_buffers 8 128k; 
        include        fastcgi_params; 
    } 

}

Now restart Nginx and php-fpm by running the following commands:

sudo /etc/init.d/php8.0-fpm restart
sudo /etc/init.d/nginx restart

Create First Administrator

That's it! Apex is now fully installed and running on the server. Open your browser to https://domain.com/admin/ to visit your administration panel, and create your first administrator. If you are new to Apex, ensure to check out the various Learn by Example Guides that are available, such as the Develop Your First Package guide. If you ever have any questions or issues with Apex, feel free to post on the /r/apexpl sub Reddit.