Getting Started

Container basics

A container packages your PHP application with the exact PHP version, extensions, and web server it needs, so it runs the same on your laptop, in CI, and in production. This page covers the terms and commands you need before the installation guide.

Why run PHP in containers

  • Same environment everywhere. Mac, Windows, Linux, and your servers all run the same image.
  • Configuration lives in Git. Your compose.yml and Dockerfile describe the whole stack. You review and roll back changes like code.
  • No host lock-in. Any host that runs containers can run your app.
  • Scaling and rollbacks. To scale, start more containers from the image. To roll back, start the previous image.

Docker and these images are free and open source. You don't need a paid platform.

Terms you'll see

TermMeaning
ImageA read-only template for a container, such as serversideup/php:8.5-fpm-nginx.
ContainerA running instance of an image. Many containers can run from one image, each with its own processes and files.
TagThe part after the : that picks a version of an image. Our tags name the PHP version and variation: 8.5-fpm-nginx.
RegistryWhere images are stored and pulled from. We publish to Docker Hub and GitHub Packages.
VolumeA directory from your machine, or one Docker manages, mounted into a container. Files in it outlive the container.
Port mappingForwards a port on your machine to a port in the container, such as 80:8080.
Environment variableA setting passed to the container at startup. Our images read them to configure PHP and the web server.

Docker is one tool for running containers

Docker builds and runs containers. The images follow the Open Container Initiative (OCI) standard, so the same image runs on Kubernetes, Docker Swarm, HashiCorp Nomad, and other OCI platforms. These docs use Docker Compose.

Images are built in layers

An image is a stack of layers: the operating system, PHP, the web server, and our configuration. Your own Dockerfile adds layers on top, such as your code. When you pull an image, Docker only downloads the layers you don't already have.

How a compose.yml uses these terms

This is the file from the installation guide:

compose.yml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - 80:8080
    volumes:
      - ./:/var/www/html
    environment:
      PHP_MEMORY_LIMIT: "512M"
LineWhat it doesIn this file
phpNames the service. You pick the name, and commands use it.docker compose exec php php -v runs php -v in this service.
imageThe image the container runs.PHP 8.5 with NGINX. See Choosing an image.
portsForwards a port on your machine to the container, as host:container.http://localhost (port 80) reaches NGINX on 8080.
volumesMounts a folder from your machine into the container.Your project appears at /var/www/html, and edits show up on the next request without a rebuild.
environmentSets environment variables, which our images turn into PHP and web server settings at startup.PHP_MEMORY_LIMIT: "512M" sets memory_limit.

Our images run as an unprivileged user, so web servers listen on 8080 and 8443 inside the container. If another program already uses port 80 on your machine, Docker fails with "port is already allocated". Use another host port, such as 8000:8080, and visit http://localhost:8000.

The environment variable specification lists every setting you can change this way.

In production, copy your code into the image instead of mounting it. See Packaging your app for deployment.

Common Docker Compose commands

Run these from the directory that holds compose.yml.

CommandWhat it does
docker compose upCreates and starts the containers, with logs in your terminal. Press + C to stop them.
docker compose up -dSame, in the background.
docker compose psLists the project's containers and their health.
docker compose logs -fFollows the logs. Press + C to stop following.
docker compose exec php php -vRuns a command in the running php container.
docker compose stopStops the containers without removing them. docker compose start resumes them.
docker compose downStops and removes the containers and the project's network. Images and named volumes stay.
docker compose up --buildRebuilds images from your Dockerfile before starting.
docker compose down --rmi allAlso removes the images, so the next up pulls them again.
Anything a container writes outside a volume is deleted when the container is removed, including by docker compose down. Keep uploads, databases, and other data you need in a volume.

Next step

Run your first PHP container