A release is more than copying files A Laravel deployment changes code, dependencies, configuration, database structure, cached files, and sometimes runnin...
A release is more than copying files
A Laravel deployment changes code, dependencies, configuration, database structure, cached files, and sometimes running workers. A release can appear successful in the browser while queue jobs still use old code or uploaded assets resolve to the wrong storage path. A checklist should make each dependency explicit and include a recovery path.
This guide assumes a VPS or similar host. Adapt commands to your hosting model, deployment user, and process manager. Test the procedure in staging before using it for a business critical production system.
Check the environment first
Confirm the target PHP version and required extensions, Composer lockfile, database version, and writable storage and bootstrap/cache directories. The web server document root must point to Laravel's public directory, never the repository root. Keep secrets out of Git and verify APP_DEBUG is false in production.
Record the current release identifier and a database backup location before modifying the system. A database backup is useful only if restoration has been tested and the operator knows the recovery time.
Prepare the new release
Install dependencies from the committed lockfile with production options. Build frontend assets using the project lockfile. Validate that the expected files exist and that the web server can read them. If the release uses a shared storage directory, preserve the existing uploads and ensure the public storage link points to it.
Do not delete public/storage as a generic deployment step without confirming the actual target and whether it is a symlink. Deleting a real directory could remove user uploads.
Apply database changes carefully
Review migrations for locks, data backfills, and reversibility. Deploy backwards compatible schema before code that depends on it when the release spans multiple instances or long running workers. Run migrations once per deployment, then check the migration status. Avoid editing old migration files that have already run in production.
For large tables, test migration duration against a representative copy. A quick local migration gives no assurance that a production ALTER TABLE will be quick.
Cache and restart
Laravel's deployment guidance recommends caching configuration, routes, events, and views for production. Run the project's established optimization command only after environment values and assets are correct. Restart or reload queue workers so they use the new code; workers are long running and do not automatically pick up a code change.
If the app uses scheduled tasks, confirm the scheduler remains active. Check database, cache, mail, storage, and queue health using a small, safe smoke test.
Verify and recover
Open a public page, an authenticated admin page, a representative image, and a detail route. Check the application log and failed jobs after the release. For a breaking failure, roll back code and confirm the older code can read the new schema. Database rollback is not automatically safe if new records were written under the new format; plan for forward fixes or a restore when necessary.
Common mistakes
- Serving the repository root instead of public.
- Caching config before setting environment values.
- Forgetting queue workers or scheduler processes.
- Running a destructive seeder during a normal release.
- Treating a successful HTTP 200 as proof that background workflows work.
Conclusion
A good deployment is a repeatable sequence with observable checks and a known recovery route. Our cloud and DevOps service addresses the infrastructure and operating side of that process.
References