How to Install Statamic on Ubuntu

Prerequisites#

To install Statamic on an Ubuntu instance you will need the following:

• An Ubuntu 22.04 or 20.04 VPS with root access enabled or a user with Sudo privileges (you can follow our Digital Ocean or Linode guides to get yours set up)
• A server with at least 1GB memory
• A valid domain name pointed to your server and SSL certificate in place
• PHP 8.1+

Update Packages#

If this is the first time using apt in this session, you should sure package lists and installed packages are up to date.

sudo apt-get update
sudo apt-get upgrade
shell
shell

Install PHP & Required Modules#

sudo apt install php-common php-fpm php-json php-mbstring zip unzip php-zip php-cli php-xml php-tokenizer php-curl -y
shell
shell

Install Composer#

Install Composer with the following command:

curl -sS https://getcomposer.org/installer | php
curl
curl

Next, you need to move the composer.phar file to a globally accessible directory and update its permissions.

sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
shell
shell

Now you can check to make sure Composer is installed and configured correctly by running this command:

composer
shell
shell

Install Statamic CLI#

Next up, let's install the Statamic CLI. To do this, run the following command in your terminal:

composer global require statamic/cli
shell
shell

Upon installation, you can now use the statamic new command to spin up fresh Statamic sites with a CLI setup wizard 🧙‍♂️ to guide you through a variety of settings and options.

Our CLI is essentially a super fancy wrapper around the composer create-project command. You can choose to not install it, but only at your own annoyance.

Create a new Statamic Application#

Now we'll create a new Statamic application using the statamic new command.

First, navigate to the /var/www directory:

cd /var/www
shell
shell

Next, run the following install command:

statamic new example.com
shell
shell

Hot Tip!

If you run into a TTY error like TTY mode requires /dev/tty to be read/writable, you can simulate TTY by calling script and using the --no-interaction flag.

script -q -c "statamic new --no-interaction example.com"
antlers
antlers

Set Permissions#

Once Statamic is installed, you'll need to grant appropriate permissions to the non-root user so Statamic and Laravel can write to the necessary system directories.

sudo chmod -R 755 /var/www/example.com
sudo chown -R www-data:www-data /var/www/example.com
sudo chown -R www-data:www-data /var/www/example.com/storage
sudo chown -R www-data:www-data /var/www/example.com/content
sudo chown -R www-data:www-data /var/www/example.com/bootstrap/cache
shell
shell

Install & Configure Nginx#

Next, install Nginx with the following command:

sudo apt install nginx -y
shell
shell

After the install completes, Nginx will start automatically. You can verify the service by running the following the command:

sudo systemctl status nginx
shell
shell

Next, let's set up the minimum recommended config file to serve your site. Create a new file with vim (or your command line editor of choice) at /etc/nginx/sites-available/example.com, making sure to replace example.com everywhere with your desired domain.

server {
    listen 80;
    server_name example.com; 
    root /var/www/example.com/public;
 
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";
 
    index index.html index.htm index.php;
 
    charset utf-8;
 
    set $try_location @static;
 
    if ($request_method != GET) {
        set $try_location @not_static;
    }
 
    if ($args ~* "live-preview=(.*)") {
        set $try_location @not_static;
    }
 
    location / {
        try_files $uri $try_location;
    }
 
    location @static {
        try_files /static${uri}_$args.html $uri $uri/ /index.php?$args;
    }
 
    location @not_static {
        try_files $uri /index.php?$args;
    }
 
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
 
    error_page 404 /index.php;
 
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
 
    location ~ /\.(?!well-known).* {
        deny all;
    }
}
php
php

Hot Tip!

You should ensure that the PHP path matches the version of PHP-FPM you have installed.

For example: the example config above specifies fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;, but if you update all packages, you may end up with a later version.

You can confirm that the configuration doesn’t contain any syntax errors with the following command:

sudo nginx -t
shell
shell

You should see output similar to this:

# Output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
shell
shell

Time to reload Nginx and apply these changes:

sudo systemctl reload nginx
shell
shell

Now visit your IP Address or https://example.com (but like the actual domain) if you've pointed your domain's A Record and you should see the Statamic landing page.

Conclusion#

That's pretty much it. Time for you to take it from here.

If this is your production server, you'll probably want to add cache expiry headers and so on, but those rules and what you cache to the browser are all up to you.

There are many other variables at play when building your own server. It's unrealistic to think we've covered them all here, or that this article won't get out of date at times as things change.

If you run into issues not covered here, you may want to read through this discussion where several folks work through many edge cases happening all at once.