Docker Dev Stack on a VPS: an environment ready for coding

A local development environment works, but it remains tied to a single machine: switching workstations, onboarding a new collaborator or accessing it from another country all become points of friction. By centralizing your Docker stack on a VPS, you have a shared development server, always on, accessible via SSH or browser from anywhere. You also gain in reproducibility: each service is defined in a docker-compose.yml file, which eliminates the notorious "it works on my machine" problem.

A full stack with PostgreSQL, Redis, Nginx and an application uses 4 GB of RAM at minimum in practice — below that, the Docker OOM killer interrupts PostgreSQL or Redis during a migration with no application-level error message. The VPS must run Ubuntu 22.04 LTS or Debian 12, with Docker Engine 26+ and Docker Compose v2.22+ installed (the command is written docker compose, without a hyphen). Check the version with docker compose version: the watch feature used later requires v2.22 at minimum, released in September 2023.

The ServOrbit reference stack assembles six complementary services.

Nginx acts as the front reverse proxy: it receives HTTP requests on port 80 and routes them to PHP-FPM (via FastCGI) or to a Node.js server. The nginx/default.conf configuration is mounted as a volume to remain editable without rebuilding the image.

PHP-FPM 8.3 (or Node.js 22 depending on the stack profile) runs the application code. Both variants are available in the ServOrbit Marketplace; the docker-compose.yml includes both services — disable the one you don't need with profiles.

PostgreSQL 16 stores persistent data. Port 5432 is not exposed on the host by default — only the internal Docker network dev_net has access, which prevents any accidental exposure on the VPS's public IP.

Redis 7 serves as cache and message broker. Like PostgreSQL, it stays on the internal network (port 6379) and is accessible from application code via the service name redis.

Mailpit 1.x replaces a real SMTP server in development: it captures all outgoing emails and exposes them in a web interface on port 8025. No special SMTP configuration on the application side — simply point to mailpit:1025.

Adminer (port 8080) provides a lightweight web interface to manage PostgreSQL or MySQL without a heavy client. It is accessible only from the machine itself or via SSH tunnel.

The stack's docker-compose.yml declares three named volumes — postgres_data, redis_data and app_data — mounted in /var/lib/postgresql/data, /data and /var/www/html respectively. These volumes survive a docker compose down: database data and uploaded files remain intact between restarts.

All services share the internal dev_net bridge network. Nginx is the only service exposing a port on the host (80); the others remain isolated and communicate by service name — postgres, redis, mailpit.

Sensitive variables (PostgreSQL password, application secret key) are never written directly in docker-compose.yml. They are read from /opt/docker-dev-stack/.env via the env_file directive. This file is excluded from the Git repository by .gitignore. Non-sensitive environment variables (port, PHP version, database name) can appear directly in the Compose file under the environment key, so they are visible during code review.

PostgreSQL, Adminer and Redis are not exposed on the VPS's public IP. To access them from your local workstation, open an SSH tunnel: ssh -L 5432:localhost:5432 -L 8080:localhost:8080 root@<IP_VPS> creates two local forwards — your laptop's port 5432 points to PostgreSQL, and port 8080 to Adminer. Your usual SQL client then connects on localhost:5432 as if the database were running locally.

For HTTP services (Nginx, Mailpit), two approaches are available. If you have a domain name, configure an A record pointing to the VPS IP and set up Nginx to serve dev.yourdomain.com over plain HTTP (no TLS needed for a development environment). If you work without a domain, an SSH tunnel is sufficient: ssh -L 8025:localhost:8025 root@<IP_VPS> gives access to Mailpit on localhost:8025.

In development, the .env file centralizes all secrets. In production, Docker secrets (docker secret) or an external secrets manager (Vault, AWS Secrets Manager) replace the flat file — an accidentally versioned .env exposes credentials in the Git history.

Resource limits (deploy.resources.limits) are worth setting in dev: PostgreSQL can consume all available RAM if a query goes wrong. Start with memory: 512m on PostgreSQL, memory: 256m on Redis and memory: 256m on PHP-FPM, then adjust based on actual usage profiles.

Never mount the Docker socket (/var/run/docker.sock) in an application container unless strictly necessary: a container with socket access can launch other containers with root privileges on the host. In development the risk is limited, but habits formed here tend to be reproduced in production.

Port already in use. The error Bind for 0.0.0.0:80 failed: port is already allocated means a host service (Apache, system nginx) is already listening on port 80. Stop the system service (systemctl stop nginx or systemctl stop apache2) or change the host port in docker-compose.yml ("8080:80") and access the stack on port 8080.

Volume permissions. The Permission denied error on a mounted volume often comes from a container uid/gid different from the host's. Add user: "1000:1000" in the affected service, or change the host directory permissions with chown -R 1000:1000 /opt/docker-dev-stack/app.

Bridge network not found. The message network dev_net declared as external, but could not be found appears if you use external: true on a network not yet created. Remove external: true: Docker Compose creates the network automatically on the first docker compose up.

Insufficient RAM. PostgreSQL displays FATAL: out of memory or keeps restarting if the VPS is undersized. Check with free -m: at least 4 GB must be available for the full stack. Reduce shared_buffers in the PostgreSQL configuration (command: postgres -c shared_buffers=128MB) or upgrade to a larger VPS plan.