Pular para o conteúdo

Como criar ambiente Docker com PHP, Apache, PostgreSQL e pgAdmin

Brayan Monteiro Brayan Monteiro
4 min de leitura
Logos centralizadas do apache, docker e pgAdmin, do artigo Como criar ambiente Docker com PHP, Apache, PostgreSQL e pgAdmin
Compartilhar:

Tu já passou pela situação de instalar PHP, Postgres e um gerenciador de banco direto na máquina e, três projetos depois, nada mais bate com nada? Pois é. Neste artigo tu sai com um ambiente completo rodando em um único docker compose up: PHP 8.3 com Apache, PostgreSQL 16 e pgAdmin, tudo conversando entre si e com o banco persistindo os dados. É pra quem programa em PHP e quer parar de sofrer com versão de banco e extensão faltando.

O que a gente vai montar

Três containers, uma rede interna e um volume:

  • app: PHP 8.3 + Apache, com a extensão pdo_pgsql instalada.
  • db: PostgreSQL 16, com healthcheck pra app só subir quando o banco estiver pronto.
  • pgadmin: interface web pra tu enxergar e mexer no banco.
  • volume pgdata: pra não perder os dados quando derrubar o container.

Se tu ainda não tem o Docker instalado, dá uma olhada no meu texto O que é Docker? e depois volta aqui. Pra quem usa Linux, tem também o ambiente de desenvolvimento PHP no Linux.

1. Estrutura de pastas

Cria uma pasta pro projeto e deixa assim:

meu-projeto/
├── docker-compose.yml
├── Dockerfile
├── .env
├── .gitignore
└── src/
    └── index.php

2. Dockerfile do PHP com Apache

A imagem oficial php:8.3-apache não vem com driver do Postgres. Sem ele, tu toma o famoso could not find driver na primeira conexão. Então a gente instala:

FROM php:8.3-apache

RUN apt-get update \
    && apt-get install -y --no-install-recommends libpq-dev \
    && docker-php-ext-install pdo pdo_pgsql \
    && a2enmod rewrite \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /var/www/html

O a2enmod rewrite já deixa o mod_rewrite ligado, porque cedo ou tarde tu vai querer URL amigável ou um framework.

3. Variáveis de ambiente (.env)

Nada de senha escrita direto no docker-compose.yml. Cria o arquivo .env:

POSTGRES_DB=app_db
POSTGRES_USER=app_user
POSTGRES_PASSWORD=troque_essa_senha

[email protected]
PGADMIN_DEFAULT_PASSWORD=troque_essa_tambem

E no .gitignore, bota:

.env

Por fora, se tu quiser compartilhar o projeto, cria um .env.example com valores de mentirinha e sobe esse no Git.

4. docker-compose.yml

Agora a parte principal:

services:
  app:
    build: .
    container_name: php_app
    ports:
      - "8080:80"
    volumes:
      - ./src:/var/www/html
    env_file:
      - .env
    environment:
      DB_HOST: db
      DB_PORT: 5432
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    container_name: pg_db
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  pgadmin:
    image: dpage/pgadmin4:8.14
    container_name: pg_admin
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:5050:80"
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - db

volumes:
  pgdata:
  pgadmin_data:

Pontos que merecem atenção:

  • depends_on com service_healthy: sem isso, o PHP sobe antes do Postgres terminar de inicializar e a primeira requisição quebra.
  • $${...} no healthcheck: o $$ escapa o cifrão pro Compose não tentar substituir a variável ele mesmo.
  • 127.0.0.1:5432:5432: expõe o banco só pra tua máquina. Se tu deixar só 5432:5432, o banco fica aberto pra rede toda. Em notebook em rede de café, isso é pedir problema.
  • Versão da imagem fixa: postgres:16-alpine e pgadmin4:8.14 em vez de latest. Assim o ambiente de hoje é o mesmo do mês que vem.
  • Dois volumes: um pros dados do Postgres e outro pras configurações do pgAdmin, pra tu não precisar cadastrar o servidor toda vez.

5. Testando a conexão com PDO

Cria o src/index.php:

<?php

declare(strict_types=1);

$host = getenv('DB_HOST') ?: 'db';
$port = getenv('DB_PORT') ?: '5432';
$name = getenv('POSTGRES_DB');
$user = getenv('POSTGRES_USER');
$pass = getenv('POSTGRES_PASSWORD');

$dsn = "pgsql:host={$host};port={$port};dbname={$name}";

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);

    $versao = $pdo->query('SELECT version()')->fetchColumn();

    echo '<h1>Conectou, bichinho!</h1>';
    echo '<p>PHP ' . htmlspecialchars(PHP_VERSION, ENT_QUOTES, 'UTF-8') . '</p>';
    echo '<p>' . htmlspecialchars((string) $versao, ENT_QUOTES, 'UTF-8') . '</p>';
} catch (PDOException $e) {
    http_response_code(500);
    echo 'Falha na conexão. Veja os logs do container.';
    error_log($e->getMessage());
}

Repara que a mensagem de erro do banco vai pro log e não pra tela. Mostrar $e->getMessage() pro usuário vaza host, usuário e às vezes mais coisa. Se tu quer entender melhor o PDO, tem o O que é PDO em PHP? aqui no blog.

6. Subindo tudo

docker compose up -d --build
docker compose ps

Quando os três aparecerem como running (e o db como healthy), abre:

  • App: http://localhost:8080
  • pgAdmin: http://localhost:5050

Se aparecer a versão do PHP e do PostgreSQL na tela, está tudo certo.

7. Conectando o pgAdmin no banco

Entra no pgAdmin com o e-mail e a senha do .env, clica em Add New Server e preenche:

  • Name: o que tu quiser (ex.: Local)
  • Aba Connection:
    • Host name/address: db
    • Port: 5432
    • Maintenance database: o valor de POSTGRES_DB
    • Username e Password: os do .env

O erro clássico aqui é botar localhost no host. Dentro do container do pgAdmin, localhost é ele mesmo, e não o teu computador nem o Postgres. O nome certo é o nome do serviço no Compose: db.

8. Meu perrengue (e o que eu aprendi)

Troca este bloco pela tua experiência real: versão que tu usou, o erro que deu e o print. Abaixo vai a base que eu sugiro, edita no teu jeito.

Na primeira vez que montei esse ambiente, bati em três coisas:

  1. could not find driver: esqueci de instalar o pdo_pgsql no Dockerfile. Só com a imagem pura do PHP não funciona.
  2. pgAdmin não subia com o e-mail [email protected]: as versões mais novas rejeitam domínio .local no e-mail padrão. Usar um domínio com cara de real (como exemplo.com) resolveu.
  3. Mudei a senha no .env e o banco continuou com a antiga: o Postgres só lê essas variáveis na primeira inicialização do volume. Pra recriar do zero em ambiente de desenvolvimento:
docker compose down -v
docker compose up -d --build

Cuidado: o -v apaga os volumes, ou seja, apaga os dados. Só usa isso em dev.

9. Comandos que tu vai usar todo dia

# ver logs de um serviço
docker compose logs -f db

# abrir o psql dentro do container
docker compose exec db psql -U app_user -d app_db

# entrar no container do PHP
docker compose exec app bash

# parar tudo sem apagar dados
docker compose down

10. Boas práticas antes de levar pra produção

Esse setup é pra desenvolvimento. Pra produção, muda pelo menos:

  • Não expor a porta do Postgres nem do pgAdmin pra internet.
  • Senhas fortes e guardadas em um gerenciador de segredos, não em arquivo solto.
  • Criar um usuário de aplicação com permissão mínima, em vez de usar o dono do banco pra tudo.
  • Backup automático do volume (pg_dump agendado, por exemplo).
  • Remover o pgAdmin da stack ou colocar atrás de autenticação forte.

Próximos passos

Com o ambiente de pé, tu já pode treinar de verdade. Dois caminhos que combinam com esse setup:

Se tu fez, deu certo ou deu ruim em algum ponto, deixa nos comentários que eu respondo.

Referências

Palavras-chave:

#Ambiente Docker com PHP #Apache #PostgreSQL e pgAdmin

Sobre o autor

Brayan Monteiro

Brayan Monteiro

Bacharel em Sistemas de Informação pela Faculdade Maurício de Nassau e desenvolvedor de software. Produzo conteúdo e gerencio blogs. Sou especialista em desenvolvimento web e SEO de sites.

Continue lendo

Postagens relacionadas

Discussão

Comentários

Nenhum comentário ainda. Seja o primeiro a comentar.