PHP8 - Laravel 12

**# Deploying to Combell Webhosting

Free Hosting for Students

As a student of Thomas More, you can claim free web hosting and a free .be domain name at combell.com.

Log in at https://www.academicsoftware.eu/ and select Combell Web hosting (Linux).
- Search for Combell web hosting.
- Follow the instruction and select the Linux web hosting option.
- Request a License and follow the on-screen instructions. (IMPORTANT: only .be domain names are included for free!)

Update PHP Settings

Before uploading your project, you need to ensure the server environment matches your local setup.

Log in to your Combell dashboard: https://my.combell.com/
Navigate to My Products > Web hosting and click Manage hosting for your domain.
In the left sidebar, go to PHP settings.
- General settings: Select the same PHP version you used for local development (we use PHP 8.3).
- php.ini directives: The default settings are usually sufficient. However, if your project has specific requirements, you can adjust them here.

Add a Subdomain

We will deploy our Laravel site to a dedicated subdomain, such as vinylshop.yourdomain.be.

In the left sidebar, go to Websites & SSL.
Click Add subdomain.
- Domain name: Enter your chosen subdomain (e.g., vinylshop.yourdomain.be).
- Home directory: This is the most critical step. You must point the subdomain's document root to the public directory of your Laravel application.
  - Uncheck the default folder option.
  - Set the Folder on the server to /vinylshop/public.

After creating the subdomain, find it in the list and go to its SSL settings.

Click the button to Enable Let's Encrypt and then activate Force HTTPS to ensure all traffic is secure.

Put Your Website Online

Compile Assets for Production

Your local development server uses Vite to serve assets on the fly. For a production environment, these assets must be compiled and minified into static files.

Run the build command in your local project terminal: npm run build.
This command creates a public/build directory containing the optimized CSS and JavaScript files.
See also Config -> Laravel Vite -> Compile for Production.

The @vite directive now points to the compiled, versioned asset files in the build directory.

html

<head>
    <meta charset="UTF-8">
    ...
    <link rel="stylesheet" href="https://vinylshop.it-fact.be/build/assets/app.9d96761f.css" />
    <script type="module" src="https://vinylshop.it-fact.be/build/assets/app.ab93cf8a.js"></script>
</head>

Configure PhpStorm for Deployment

We'll use SFTP to transfer our project files. PhpStorm's built-in deployment tools make this easy to configure.

First, find your SSH credentials in the Combell dashboard under SSH access.
In PhpStorm, go to Tools -> Deployment -> Configuration....
- Click the + icon, choose SFTP, and name the configuration (e.g., "Combell").
On the Connection tab, click the ... button next to SSH configuration.

Fill in the host, username, and password from your Combell dashboard and test the connection.

Back on the Connection tab:
- Set the Root path to the directory where you will upload your project (e.g., /vinylshop).
- Set the Web server URL to your subdomain's full URL (e.g., https://vinylshop.yourdomain.be).

Switch to the Mappings tab:
- The Local path should be the root of your local Laravel project.
- Set the Deployment path and the Web path to /. This makes the root path you defined earlier (/vinylshop) correspond to the root of your project.

Upload the Files to Your Hosting

Open the Remote Host tool window in PhpStorm (usually in the right-side toolbar).
Select all your project files and folders except for node_modules and tests.
Right-click the selection and choose Deployment -> Upload to Combell.
After the initial upload, ensure the root files .env and composer.json are also uploaded.

Clean Up Remote Folders

After uploading, a few cleanup steps are necessary.

In the remote file browser, navigate to the database folder and delete everything except your database.sqlite file.
Navigate to the remote public folder and delete the hot file and the storage directory.
The storage folder on the server must be a symbolic link, not a real directory.

Create the Storage Symlink

Laravel needs a symbolic link from public/storage to storage/app/public to serve images and other assets correctly. We can create this by running an Artisan command via a temporary route.

Open your local routes/web.php file and add this temporary route:

php

Route::get('/symlink', function () {
    Artisan::call('storage:link');
});

Upload the modified web.php file to the server.
Visit https://vinylshop.yourdomain.be/symlink in your browser. You'll see a blank page, but the link will be created on the server.
Important: Remove the symlink route from your local web.php file and upload it again to clean up.

Now, test your live site by visiting a page that relies on the database and stored images, like the shop page.

Update the Remote .env File

The .env file on your server needs to be configured for a production environment. Double-click the remote .env file in PhpStorm to edit it.

Disable Debugging and Set the Correct URL

bash

APP_NAME="The Vinyl Shop"
APP_ENV=production                                  # change from local to production
APP_KEY=base64:e77jPGGcqZ4sNADHI5f/icC+LFnBw34hpRJKSf2ftnI=
APP_DEBUG=false                                     # change from true to false
APP_URL=https://vinylshop.yourdomain.be             # set the URL to your domain

By setting APP_DEBUG=false, visitors will see a generic 500 | Server Error page instead of detailed error information if something goes wrong.

TIP

If you encounter errors on the production server, you can temporarily set APP_DEBUG to true to see detailed error messages for debugging. Remember to set it back to false afterward.

Configure a Real Mail Server

Your application needs a real SMTP server to send emails for features like password resets and order confirmations.

TIP

For best deliverability, always send emails from a real address associated with your domain. Emails from fake senders (e.g., @example.com) are likely to be marked as spam.
Your application (contact page, reset password page) needs a real outgoing mail server (SMTP server) to send out the emails.

Go to your email settings in the Combell dashboard and create a new mailbox (e.g., admin@yourdomain.be).

-** Use the credentials for the newly created mailbox to update the MAIL_* variables in your remote .env file.

bash

MAIL_MAILER=smtp
MAIL_SCHEME=null
MAIL_HOST=smtp-auth.mailprotect.be      # change from 127.0.0.1 to smtp-auth.mailprotect.be
MAIL_PORT=465                           # change form 1025 to 465
MAIL_USERNAME=admin@yourdomain.be       # your email address
MAIL_PASSWORD=xxxxx                     # your email password
MAIL_FROM_ADDRESS=admin@yourdomain.be   # your email address
MAIL_FROM_NAME="${APP_NAME}"

Save the remote .env file using the Upload to Default Server button in PhpStorm's notification bar.

WARNING

If you haven't already, add a user to your remote database with a real, working email address that you can access (e.g., your Thomas More email).

Test the configuration by requesting a password reset for that user. You should receive the email in your inbox.

Updates and Maintenance

Deploying is not a one-time event. Here's how to handle future updates.

When you delete a local file, remember to delete it from the remote server as well.
For simple changes to backend files (Livewire components, middleware, routes, etc.), you can upload them individually.
When you update Composer packages (composer update), it's safest to delete the entire remote vendor folder and re-upload the new one from your local machine.

IMPORTANT: Updating Frontend Assets or Views

When you modify any files that affect the frontend build (e.g., resources/js, resources/css, or Blade files in resources/views/...), you must follow this specific process to avoid serving stale assets:

Stop your local Vite development server (composer run dev).
Rebuild your assets for production by running npm run build.
On the remote server, delete the entire public/build folder.
Upload the new public/build folder from your local machine to the remote server.
Upload any changed Blade view files from your resources/views/... folder.
Crucially, if the public/hot file exists on the remote server, delete it.
You can now restart your local development server (composer run dev).

The `hot` File Explained

The public/hot file is a key part of Vite's development process.

When composer run dev is active, this file is created and contains the URL of the local development server (e.g., http://127.0.0.1:5173). The @vite directive reads this file and injects scripts that point directly to the dev server, enabling Hot Module Replacement.
When you run npm run build for production, this file is automatically deleted. The @vite directive then falls back to pointing to the static, compiled assets in the public/build directory.

WARNING

This is why you must always delete the public/hot file from the production server. If it's present, your live site will try (and fail) to load assets from your local machine, breaking all styles and scripts.

Caching Problems

Sometimes, even after updating files, the server might still serve an old version due to Laravel's internal caching.

To solve this, you need to clear the application cache on the remote server.
In your SFTP client, navigate to the bootstrap/cache directory.
Delete all the files inside this folder.
Do not delete the cache folder itself.

Update PHP Settings ​

Add a Subdomain ​

Put Your Website Online ​

Compile Assets for Production ​

Configure PhpStorm for Deployment ​

Upload the Files to Your Hosting ​

Clean Up Remote Folders ​

Create the Storage Symlink ​

Update the Remote .env File ​

Disable Debugging and Set the Correct URL ​

Configure a Real Mail Server ​

Updates and Maintenance ​

The hot File Explained ​

Caching Problems ​