Get composer (php dependency manager) to run on a docker image build

Get composer (php dependency manager) to run on a docker image build

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Get composer (php dependency manager) to run on a docker image build

You can absolutely use Composer to manage PHP dependencies inside a Docker container, but there's a critical distinction between running composer update during the image build process versus relying on an interactive session or an ONBUILD instruction. The issue you are facing—where the vendor directory and composer.lock file do not appear after building the image—is almost certainly due to how Docker layers handle file permissions, specifically regarding the www-data user versus the root user.

When you install Composer using the official script:

RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

Composer is installed globally for the root user. However, when your application runs inside a container based on php:7.0.2-apache, the web server (Apache) and PHP-FPM typically run as the www-data user to adhere to security best practices. If the working directory (/var/www/html) is owned by root or lacks write permissions for www-data, the Composer process will fail silently during the build phase because it cannot create the output files, even if the download completes successfully.

To fix this, you must ensure that the directory where Composer writes its artifacts is writable by the user that executes the command. In the standard PHP Docker images, the root user owns the default working directories unless explicitly changed during the image setup. If you run composer update as root in a layer owned by root, it succeeds. However, if subsequent layers or runtime processes expect www-data ownership and the directory wasn't prepared correctly, permission errors can manifest.

A robust pattern involves explicitly changing ownership of the working directory to match the running user before executing Composer:

RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 775 /var/www/html

# Now run composer as the appropriate user or ensure permissions are set correctly
USER www-data
WORKDIR /var/www/html
COPY files/composer.json ./
RUN composer update

Alternatively, you can keep everything under root during the build but ensure the composer binary is executable and that the directory is writable. However, mixing users requires careful attention to ownership. If your goal is to have a clean, reproducible image where dependencies are installed once at build time (a common practice known as "build-time caching"), using RUN composer update directly in the Dockerfile is standard. This approach embeds the vendor directory into the final image layer.

The ONBUILD instruction you attempted serves a different purpose: it copies files from the current context and then runs a build step on a new image being derived from yours. If you are building the base image yourself and want to install dependencies immediately, stick with a direct RUN composer update. Avoid ONBUILD unless you are distributing a base image that other applications will extend.

Remember that running Composer during the build phase means those files become part of the immutable image layer. This is usually desirable for performance, as it avoids installing dependencies every time a container starts up. Just ensure your composer.json and composer.lock are committed to your repository so that the build process is deterministic. If you rely on caching layers in CI/CD environments, this approach maximizes build efficiency.

Our network