Docker Symfony

A Docker set-up for Symfony projects using nginx, PHP-FPM, MySQL and Redis. Also includes xDebug, Doctrine ORM and a basic first page in Symfony, as per their docs.

🔑 Getting Started

The following only needs to be completed when you're setting up the project for the first time. Afterwards, simply (re-)start all required services and containers using the relevant command in Docker Up below.

1. Basic prep

• Create the .env file with cp .env.example .env and set required values
• Create a Docker-specific .env file with cp docker/.env.docker.example docker/.env.docker and set required values
• Find and replace all references to rename-me in this repo to your desired project value

2. Enable HTTPS for local development

• To get https working with a self-signed certificate, we'll use mkcert:

# Install mkcert if needed (@link https://github.com/FiloSottile/mkcert)
brew install mkcert
brew install nss # if you use Firefox

# Create root CA (see in Keychain Access app: System > Certificates)
mkcert -install

# Create specific certs
mkcert \
-key-file docker/nginx/certs/rename-me-test-key.pem \
-cert-file docker/nginx/certs/rename-me-test-cert.pem \
rename-me.test

• Add the following to your /etc/hosts file:

127.0.0.1 rename-me.test

3. Start Docker Containers

• Run the relevant command in Docker Up below.

4. Set the APP_SECRET

• docker compose exec php-service php -r "echo bin2hex(random_bytes(16)) . PHP_EOL;"
  • Put the resulting value into your /.env file's APP_SECRET=

5. Install dependencies

• docker compose exec php-service composer install

6. View in browser

• Url: https://rename-me.test / the first page route

🐳 Docker Up

# dev (utilizes docker compose override) 
docker compose --env-file docker/.env.docker up

# prod
docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file docker/.env.docker up

🐞 xDebug

Enable in dev

To start the dev container with xDebug enabled (it's disabled by default), ensure the following is in the .env.docker:

XDEBUG_MODE=debug

In PhpStorm

• In Settings > PHP, ensure the Debug port matches the port in set in ./docker/php/conf.d/xdebug.ini
• In Settings > PHP > Servers, ensure the local app directory is mapped to /var/www/html, as per the docker set-up.

🌲 .env Fun

We are not using the env_file option in docker-compose.yml, because mixing env_file and environment can lead to confusing overrides. You can use env_file alone, but being explicit with environment makes it easy to see which variables each service depends on.

The docker-compose.yml therefore uses the environment key, with values coming from the .env.docker file. This keeps configuration values centralized in one place while still making dependencies visible in the Docker Compose file.

We separate Docker .env files from Symfony .env files on purpose. By the time Symfony runs, the environment variables provided by Docker are already available at the system level inside the container (you can confirm this by inspecting the container).

To inspect which Symfony .env values are being used and which files they come from (e.g. .env.local overriding .env), run the following inside the php-service container:

bin/console debug:dotenv

🎁 Production Considerations

Currently, this is dev-focused and would require further work to make prod-ready. At scale, production deployment usually moves beyond Docker Compose toward orchestrators.