Deploying Symfony 8 to cPanel Step by Step guide.

Table of Contents

• Introduction
• Double-check everything
• Configure your Environment Variables
• Install/Update your Vendors
• Clear your Symfony Cache
• Install symfony/apache-pack
• Update composer.json public directory
• Build the assets
• Update Kernel.php
• Upload the project to cPanel
• Final Thoughts

Introduction

I'm new to Symfony and recently, I deployed a Symfony app to a shared hosting environment with cPanel.

I could not figure out the best way to do it, let alone find useful resources online as most of them are outdated.

I faced a lot of errors like: failing to load the app with a 500 Internal Server Error, some static assets not loading, etc. I figured it out in the end. This motivated me to write this post to reduce frustration for other Symfony newbies like me.

Most deployment guides online assume you can run Composer, clear caches, execute migrations, and run Symfony commands directly on the server. In shared hosting environments, that is often not possible so, my examples will assume you don't have it installed on the server.

Alright, let's get into it.

1. Double-check everything

The first step to building for production is double-checking everything if it's in intact. Yes, this is very important. In my case, I was faced with some static image assets failing to load because of wrong reference which was ignored on dev mode. I had something like: asset('/images/<filename>)which was working in dev mode but failed to load the image in prod. the paths had to be like:asset('images/'). This was after checking how I defined other assets. So avoid things like this before hand.

2. Configure your Environment Variables

For this, we will use the dotenv:dump command which is not registered by default, so you must register first in your services:

# config/services.yaml
services:
    Symfony\Component\Dotenv\Command\DotenvDumpCommand: ~

Then, run the command below. After running this command, Symfony will create and load the .env.local.php file to get the environment variables and will not spend time parsing the .env files.

APP_ENV=prod APP_DEBUG=0 php bin/console dotenv:dump

3. Install/Update your Vendors

composer install --no-dev --optimize-autoloader

4. Clear your Symfony Cache

Make sure you clear and warm-up your Symfony cache by running the following command:

APP_ENV=prod APP_DEBUG=0 php bin/console cache:clear

5. Install symfony/apache-pack package

You can skip step if you already have it installed. The Symfony deployment documentation mentions that Apache shared hosting may need apache-pack. To be safe, install it:

composer require symfony/apache-pack

This creates the .htaccess configuration required for Symfony routing.

Without it, Apache may display directory listings or fail to route requests through index.php.

6. Update composer.json to override the public directory.

Since cPanel uses public_html as the public folder, add the following to composer.json file:

"extra": {
        "...": "...",
        "public-dir": "public_html"
    }

Note: composer.json is primarily used during the build process. Composer, Symfony Flex, recipes, asset installation, and other tools read it when Composer commands run.So, editing it after deployment does not reconfigure Symfony.

Reference: Override Public Dir

7. Build the assets

I'm using assetMapper for this. I had tailwindcss installed so I had to build it first then compile the assets. Run the following commands in order:

symfony console tailwind:build
symfony console asset-map:compile

Note: You may encounter an error that public_html directory does not exist. Don't panic, just edit the public folder to public_html and the error should be fixed.

8. Update src/Kernel.php file.

This step is important before we select the files we have to upload to cPanel. We need to define the project_dir.

This parameter stores the absolute path of the root directory of your Symfony application, which is used by applications to perform operations with file paths relative to the project's root directory.

By default, its value is calculated automatically as the directory where the main composer.json file is stored. This value is also exposed via the getProjectDir() method of the kernel class.

Add the following code:

// src/Kernel.php
namespace App;

use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel
{
    // ...

    public function getProjectDir(): string
    {
        return \dirname(__DIR__);
    }
}

Note: You can skip this step and upload the composer.json file together with the composer.lock(not really needed) since the Kernel an use it to determine the project_dir. However, the best way to do it is to add the above code.

Reference: kernel Project Dir

9. Upload the project to cPanel

Important folders and files to upload:

bin/
config/
migrations/
public_html/ # in our case
src/
templates/
translations/ # if being used
vendor/
var/
.env.local.php

Exclude:

.git/
.github/
node_modules/
tests/
var/cache/
var/log/
assets/ # Note: this is not the public/assets

Symfony recreates cache and log files automatically.

Now, zip the selected folders and files then, upload them. The rest is history, you're a developer.

If you have reached this far, congratulations, your app should be running in production by now.

Final Thoughts

Deploying Symfony 8 on shared hosting is definitely possible.

The biggest challenge is understanding which files affect the build process and which files affect runtime behaviour. Upon understanding the distinction, deployment became much more easy.

Read more here: How to Deploy a Symfony Application

Thank you!