Deploying to Linux When Developing on Windows

PHPMaker User Submitted Tips (PHPMaker)
1

1. Key Principle

Windows and Linux use different filesystem conventions:

Windows Linux
\ path separator / path separator
case-insensitive case-sensitive

Symfony's compiled container (in var/cache) may contain absolute paths, so Windows-built cache can break on Linux.

If you get errors related to missing directories or incorrect paths, generate cache on the Linux server after deployment.

2. Prepare the Project on Windows

Change the Environment to Production. Review Notes in documentation and adjust any advanced settings as needed.

Review the settings in .env.prod.local, make sure the settings (especially the connection info) are correct for the production server.

Before uploading, clean the project by removing runtime directories:

var/cache/dev/*
var/cache/prod/*
var/log/*

This avoids uploading Windows-specific or development artifacts.

3. Upload the Project to Linux

Upload the project files and directories to your Linux server.

Note: In most cases, you can use the vendor folder generated on Windows, since Composer dependencies are generally platform-independent PHP files.

However, it is strongly recommended to run composer install on the Linux server to ensure:

  • platform requirements match the server’s PHP version and installed extensions
  • autoload files are generated correctly for Linux
  • file permissions and ownership match the web server user
  • production options such as --no-dev and --optimize-autoloader are applied

While copying vendor may work, installing dependencies on the server is safer and more reliable.

4. Install Dependencies on Linux

Run Composer on the server:

composer install --no-dev --optimize-autoloader --classmap-authoritative

This ensures optimized autoloading and removes development-only packages.

5. Fix Permissions

Symfony needs write access to:

var/cache
var/log

Ensure directories are writable by the web server user (e.g. www-data).

www-data is the default system user and group for the web server on many Linux distributions (like Ubuntu, Debian).

If these folders are not writable by www-data, Symfony will throw permission errors. On Linux, you can fix this with:

sudo chown -R www-data:www-data var/cache var/log
sudo chmod -R 775 var/cache var/log

This sets ownership to www-data and allows read/write/execute for the owner and group.

Notes

  • If you are using Nginx + PHP-FPM, the PHP-FPM process may run as a different user (check www.conf), but www-data is still common.
  • Some distributions use apache or http as the web server user instead.
  • Always check which user your web server process runs as:
    ps aux | grep apache
# or
ps aux | grep nginx

6. Generate Cache on Linux

Run cache commands only on the Linux server:

php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod

This generates cache with Linux-style paths (/) and avoids Windows path issues.

7. Recommended Workflow

The safest workflow:

  1. Develop on Windows
  2. Commit changes to Git
  3. Pull the latest code on the Linux server (Git automatically detects changed files, so you don't need to re-upload the entire project)
  4. Run Composer to install dependencies on the server
  5. Clear and warm the Symfony cache on the server

This workflow keeps deployment safe, avoids cross-platform issues, ensures your production server runs optimally, and makes updates faster and more reliable by only transferring changed files.

2

Using Git to Deploy (Private Repository with Deploy Key)

1. Check if Git is Installed

On the server, run:

git --version

  • If Git is installed, you'll see output like:

    git version 2.41.0

  • If Git is not installed, you'll get:

    bash: git: command not found

In that case, install Git: (e.g. Ubuntu)

sudo apt update
sudo apt install git -y

2. Generate a Deploy Key on the Server

Create an SSH key specifically for deployment, e.g.

ssh-keygen -t ed25519 -C "deploy@example.com"
  • Save at the default location (~/.ssh/id_ed25519)
  • Leave passphrase empty for automated deployment

Copy the public key:

cat ~/.ssh/id_ed25519.pub

Note: cat simply prints the contents of the file to the terminal. Here it lets you see your public key so you can paste it into GitHub (or another Git host).

3. Add the Deploy Key to GitHub

  1. Go to your repository → Settings → Deploy Keys → Add Deploy Key
  2. Paste the public key from the server
  3. Give it a descriptive title, e.g., "Ubuntu Production Server"
  4. Check "Allow write access" only if the server needs to push (usually not required)
  5. Save the key

4. Test the SSH Connection

On the server, test access:

ssh -T git@github.com

Expected message:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

5. Clone the Repository (First Time)

Navigate to your web root and clone using the SSH URL:

cd /var/www/
git clone git@github.com:username/project.git
cd project

Note: Replace username, project, and the path with your actual GitHub username, repository name, and desired server directory.

6. Pull Updates After That

Whenever you push changes from Windows:

cd /var/www/project
git pull origin main

Note: Replace project with your repository folder, and main with your actual branch name if different.

Git will fetch only changed files, so you don't need to re-upload the entire project each time.