Laravel + Node.js Docker Deployment: A Real-World Staging Server Setup

The Staging Server Ghost Town

Setting up a clean staging environment from scratch, especially one that perfectly mirrors production, is a common but often underestimated task. For a project running a Laravel 12 and Node.js microservices stack in Docker on a production server (api.dineshstack.ae), the need for an identical staging environment for mobile testing became critical. The existing staging server, however, was a digital graveyard. It had been used by five different developers over time, accumulating stale projects, orphaned Docker volumes, and broken Nginx configurations. The goal was clear: one clean server, one Docker network, three domains, and absolutely zero stale state.

Before touching any production infrastructure, the first critical step is a thorough survey. Assumptions about the existing setup are dangerous. Understanding the current state—what's running, what's configured, and what's lingering—is paramount. This initial assessment prevents the common pitfall of unknowingly breaking existing functionality or creating more mess.

SSH Hardening: First Line of Defense

Securing the server begins with SSH. The default SSH configuration is often too permissive. Key hardening steps include disabling root login, enforcing key-based authentication, and changing the default port. Disabling password authentication and disallowing root login are fundamental security practices. This ensures that only authorized users with specific SSH keys can access the server, and they must do so as a non-privileged user initially. The default SSH port (22) is a common target for automated attacks, so changing it adds a layer of obscurity, though it's not a substitute for strong authentication.

For this setup, the process involved several steps:

• Disable Root Login: Edit /etc/ssh/sshd_config and set PermitRootLogin no.
• Key-Based Authentication: Ensure SSH keys are distributed and configured for each user. Remove password authentication by setting PasswordAuthentication no.
• Change Default Port: Modify the Port directive in sshd_config to a non-standard port (e.g., 2222). Remember to update firewall rules accordingly.
• Firewall Configuration: Use ufw or firewalld to allow only necessary ports (SSH on the new port, HTTP/80, HTTPS/443). Block all other incoming traffic by default.

After these changes, restarting the SSH service (sudo systemctl restart sshd) is necessary. It is crucial to test SSH access on the new port from a separate terminal window before closing the current one, to avoid locking yourself out.

Docker Orchestration: The Core Stack

With the server secured, the next step is establishing the core application environment using Docker. The goal was to have three distinct services running: the Laravel application, the Node.js microservices, and a database. Docker Compose is the ideal tool for managing multi-container applications.

A typical docker-compose.yml file for this setup would define services for:

• Laravel App: This service would use a custom Dockerfile to build the PHP-FPM and Nginx environment for Laravel. It needs to mount the application code, manage environment variables (.env), and expose the necessary ports.
• Node.js Microservices: Similar to the Laravel app, this service would likely use a separate Dockerfile for the Node.js runtime, mounting code, and managing its own dependencies and environment variables.
• Database: A managed database service, such as MySQL or PostgreSQL, would be defined. For staging, using a smaller, local instance is common, but it needs to be configured with persistent storage using Docker volumes to retain data between restarts.

The docker-compose.yml file defines the relationships between these services, including network configurations and volume mappings. A common Docker network is created automatically, allowing services to communicate using their service names as hostnames (e.g., db, laravel, node_api).

Database Seeding and Migrations

A critical part of mirroring production is having realistic data in staging. This involves running database migrations and seeding the database with relevant test data. Migrations ensure the database schema is up-to-date, while seeding populates it. For this project, the Laravel application handled both.

The process typically looks like this:

1. Run Migrations: Execute docker-compose exec laravel php artisan migrate --force. The --force flag is essential when running migrations within a Docker container on a non-development environment to prevent accidental data loss.
2. Seed the Database: After migrations, run docker-compose exec laravel php artisan db:seed --force. This command triggers the database seeders defined in the Laravel application, populating tables with test data.

The challenge here is ensuring the seeding process is robust enough for testing. This might involve creating specific user accounts, populating product catalogs, or generating realistic transaction histories. The --force flag is a safeguard, reminding the developer that this operation is intended for environments where data integrity is expected and not for initial development setups where data is frequently reset.

Debugging the Elusive Login Bug

One of the most frustrating aspects of setting up complex environments is encountering persistent bugs. In this case, the user login functionality failed for six different reasons across the Laravel and Node.js services. This type of issue often stems from subtle differences between environments or misconfigurations in inter-service communication.

The debugging process involved systematic elimination:

• Check Logs: The first step is always to check the logs of all relevant containers: Laravel (PHP-FPM/Nginx), Node.js, and the database. Docker's logging drivers and docker-compose logs -f are invaluable here.
• Environment Variables: Verify that all environment variables (.env files, Docker environment variables) are correctly set and consistent across services. A common error is a mismatch in database credentials or API endpoints.
• Network Connectivity: Ensure that the Laravel application can communicate with the Node.js microservices and the database. Using docker-compose exec ping can test basic network reachability.
• CORS Issues: If the frontend (or another service) is making requests to the backend APIs, Cross-Origin Resource Sharing (CORS) misconfigurations are frequent culprits, especially when domains change between production and staging.
• Session/Token Management: Verify how sessions or JWT tokens are handled. Differences in secret keys (APP_KEY in Laravel, JWT secrets) or storage mechanisms (Redis, file) can break authentication.
• Nginx Configuration: Ensure the Nginx proxy configuration correctly forwards requests to the appropriate backend services, especially when dealing with multiple domains or subdomains.

The specific bug that took six reasons to resolve was a combination of incorrect CORS headers being sent by the Node.js service and a misconfigured session driver in Laravel that wasn't persisting across requests due to a subtle Docker networking issue. It highlights how interconnected these systems are; a fix in one area often reveals a problem in another.

SSL with Let's Encrypt

Securing the staging environment with SSL is crucial, even if it's not public-facing. Let's Encrypt provides free SSL certificates. For a Dockerized environment, this often involves integrating Certbot within one of the containers or using a dedicated Nginx container that handles certificate acquisition and renewal.

A common approach is to have the Nginx container manage the SSL certificates. When a request comes in for a domain that doesn't have a valid certificate, Nginx can redirect it to Let's Encrypt's challenge endpoint. Certbot, running either as a cron job or within the Nginx container, handles the verification and certificate issuance. The certificates are then mounted into the Nginx service's configuration.

Key considerations for Let's Encrypt in Docker:

• Persistent Storage: Certificate files and Let's Encrypt configuration must be stored in Docker volumes to persist across container restarts and allow for renewals.
• Renewal Process: Set up a cron job or a systemd timer to regularly check for certificate expiry and renew them. This renewal process needs to be able to signal Nginx to reload its configuration after a successful renewal.
• Domain Configuration: Ensure that the DNS records for the staging domains point to the server's IP address and that Nginx is configured to listen for HTTP traffic on port 80 to facilitate the Let's Encrypt validation process.

What nobody has addressed yet is the complexity of automated SSL renewal in ephemeral or highly dynamic Docker environments where container IDs can change. Ensuring the renewal process reliably picks up the correct Nginx instance or Docker service to signal for a reload is a persistent challenge.

Final Touches and Zero State

The ultimate goal was a clean server with zero stale state. This meant ensuring that any previous configurations, old Docker images, unused volumes, and lingering processes were purged. Regular cleanup commands like docker system prune -a --volumes (used with extreme caution) and manual removal of old configuration files are essential. The final setup involved a clean docker-compose.yml, hardened SSH, functional SSL, and a database seeded with the correct data, all running within a single, isolated Docker network. This meticulous process ensures the staging environment is a reliable testing ground, mirroring production without carrying any baggage from past developers or projects.