Skip to content

apache.md

Latest commit

 

History

History
266 lines (192 loc) · 9.18 KB

apache.md

File metadata and controls

266 lines (192 loc) · 9.18 KB
Raw

Páginas de Erro Personalizadas no Apache 2.4

Este guia mostra como configurar as páginas de erro do CodeAtlas no Apache 2.4, cobrindo VirtualHost, .htaccess, arquivos fora do DocumentRoot e ambientes de proxy reverso.

1. Introdução

Por padrão, o Apache exibe páginas de erro genéricas e sem identidade visual quando algo dá errado — um 404, um 500 ou qualquer outro código HTTP de erro. Substituir essas páginas por versões personalizadas melhora a experiência do usuário e mantém a identidade da sua marca mesmo em situações de falha.

O repositório codeatlasdev/404 fornece páginas prontas para os erros mais comuns:

Arquivo Código Situação
400.html 400 Requisição inválida
401.html 401 Não autorizado
403.html 403 Acesso proibido
404.html 404 Página não encontrada
429.html 429 Muitas requisições
500.html 500 Erro interno do servidor
502.html 502 Bad gateway
503.html 503 Serviço indisponível
504.html 504 Timeout do gateway

2. Estrutura de Arquivos

Clone o repositório em um diretório dedicado fora do DocumentRoot (recomendado) ou dentro dele:

git clone https://github.com/codeatlasdev/404.git /var/www/errors

Após o clone, a estrutura ficará assim:

/var/www/errors/
├── 400.html
├── 401.html
├── 403.html
├── 404.html
├── 429.html
├── 500.html
├── 502.html
├── 503.html
└── 504.html

Ajuste a propriedade dos arquivos para o usuário do Apache (www-data no Debian/Ubuntu, apache no RHEL/CentOS):

chown -R www-data:www-data /var/www/errors
chmod -R 644 /var/www/errors/*.html

3. Configuração via VirtualHost

A diretiva ErrorDocument aceita dois formatos:

  • Caminho relativo ao DocumentRoot — começa com /, o Apache serve o arquivo como uma requisição interna.
  • URL absoluta — redireciona o cliente com um 302; evite para erros de servidor (5xx), pois o redirecionamento pode falhar.

O exemplo abaixo usa um Alias (detalhado na seção 5) para servir /var/www/errors/ sob o caminho /errors/, mantendo os arquivos fora do DocumentRoot:

<VirtualHost *:80>
    ServerName exemplo.com.br
    ServerAlias www.exemplo.com.br

    DocumentRoot /var/www/exemplo

    # Aponta cada código de erro para a página personalizada
    ErrorDocument 400 /errors/400.html
    ErrorDocument 401 /errors/401.html
    ErrorDocument 403 /errors/403.html
    ErrorDocument 404 /errors/404.html
    ErrorDocument 429 /errors/429.html
    ErrorDocument 500 /errors/500.html
    ErrorDocument 502 /errors/502.html
    ErrorDocument 503 /errors/503.html
    ErrorDocument 504 /errors/504.html

    # Mapeia /errors/ para o diretório real (ver seção 5)
    Alias /errors /var/www/errors

    <Directory /var/www/errors>
        Options -Indexes -FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    <Directory /var/www/exemplo>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog  /var/log/apache2/exemplo-error.log
    CustomLog /var/log/apache2/exemplo-access.log combined
</VirtualHost>

Nota: Se as páginas de erro estiverem dentro do próprio DocumentRoot (por exemplo, em /var/www/exemplo/errors/), o Alias e o bloco <Directory> separado não são necessários — o Apache já tem acesso ao diretório servido.

4. Configuração via .htaccess

Para ambientes de hospedagem compartilhada onde você não tem acesso ao arquivo de configuração do VirtualHost, use um .htaccess na raiz do site. O servidor precisa ter AllowOverride All (ou ao menos AllowOverride FileInfo) habilitado pelo administrador.

Crie ou edite o arquivo /var/www/exemplo/.htaccess:

# Páginas de erro personalizadas — CodeAtlas
ErrorDocument 400 /errors/400.html
ErrorDocument 401 /errors/401.html
ErrorDocument 403 /errors/403.html
ErrorDocument 404 /errors/404.html
ErrorDocument 429 /errors/429.html
ErrorDocument 500 /errors/500.html
ErrorDocument 502 /errors/502.html
ErrorDocument 503 /errors/503.html
ErrorDocument 504 /errors/504.html

Se os arquivos HTML estiverem dentro do próprio DocumentRoot (ex.: public_html/errors/), os caminhos acima funcionam diretamente. Se estiverem em outro lugar, você precisará da abordagem com Alias descrita na seção seguinte — o que normalmente requer acesso ao VirtualHost ou ao httpd.conf.

5. Alias para Servir Arquivos Fora do DocumentRoot

Quando os arquivos de erro ficam em /var/www/errors/ e o DocumentRoot é /var/www/exemplo/, o Apache não serve /var/www/errors/ por padrão — ele só enxerga o que está dentro do DocumentRoot. A diretiva Alias cria um mapeamento de URL para qualquer caminho no sistema de arquivos.

# Mapeia requisições para /errors/* ao diretório /var/www/errors/
Alias /errors /var/www/errors

<Directory /var/www/errors>
    Options -Indexes -FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

Pontos de atenção:

  • O Alias deve ser declarado antes do bloco <Directory> correspondente ou dentro do VirtualHost, antes das diretivas ErrorDocument.
  • Options -Indexes impede a listagem do diretório caso alguém acesse /errors/ diretamente no navegador.
  • AllowOverride None no diretório de erros evita que um .htaccess acidental sobrescreva as permissões.
  • Se o Apache foi compilado com mod_alias desabilitado (raro), use AliasMatch ou mova os arquivos para dentro do DocumentRoot.

6. ProxyErrorOverride — Proxy Reverso

Quando o Apache funciona como proxy reverso na frente de outro servidor (Node.js, Tomcat, PHP-FPM via outro Apache, etc.), as respostas de erro vêm do backend, não do Apache. Por padrão, o Apache repassa essas respostas diretamente ao cliente, ignorando as suas diretivas ErrorDocument.

A diretiva ProxyErrorOverride On instrui o Apache a interceptar respostas de erro do backend (4xx e 5xx) e substituí-las pelas páginas configuradas localmente — comportamento equivalente ao proxy_intercept_errors on do Nginx.

<VirtualHost *:80>
    ServerName app.exemplo.com.br

    DocumentRoot /var/www/html

    # Ativa a interceptação de erros do backend
    ProxyErrorOverride On

    ProxyPass        / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    ErrorDocument 400 /errors/400.html
    ErrorDocument 401 /errors/401.html
    ErrorDocument 403 /errors/403.html
    ErrorDocument 404 /errors/404.html
    ErrorDocument 429 /errors/429.html
    ErrorDocument 500 /errors/500.html
    ErrorDocument 502 /errors/502.html
    ErrorDocument 503 /errors/503.html
    ErrorDocument 504 /errors/504.html

    Alias /errors /var/www/errors

    <Directory /var/www/errors>
        Options -Indexes -FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    ErrorLog  /var/log/apache2/app-error.log
    CustomLog /var/log/apache2/app-access.log combined
</VirtualHost>

ProxyErrorOverride requer que o módulo mod_proxy esteja carregado. Verifique com apache2ctl -M | grep proxy.

7. Teste de Configuração e Reload

Antes de recarregar o Apache, sempre valide a sintaxe para evitar downtime:

# Testa a configuração sem reiniciar o servidor
apachectl configtest

Saída esperada:

Syntax OK

Se aparecer algum erro, corrija-o antes de prosseguir. Com a configuração válida, recarregue o Apache para aplicar as mudanças sem derrubar as conexões ativas:

# Debian / Ubuntu
systemctl reload apache2

# RHEL / CentOS / Fedora
systemctl reload httpd

Para confirmar que o serviço está rodando normalmente após o reload:

systemctl status apache2

8. Verificação

Use curl para confirmar que cada código de erro retorna a página correta. A flag -o /dev/null descarta o corpo da resposta; -w imprime apenas o código HTTP.

# Testa o 404 — substitua pelo domínio real ou use localhost
curl -o /dev/null -sw "%{http_code}\n" http://exemplo.com.br/pagina-que-nao-existe
# Esperado: 404

# Verifica se o corpo da resposta contém o conteúdo da página personalizada
curl -si http://exemplo.com.br/pagina-que-nao-existe | grep -i "<title>"

Para testar os erros de servidor (5xx) sem derrubar o backend, você pode forçar temporariamente uma resposta via mod_rewrite:

# Bloco temporário de teste — remova após verificar
RewriteEngine On
RewriteRule ^/test-500$ - [R=500,L]
curl -o /dev/null -sw "%{http_code}\n" http://exemplo.com.br/test-500
# Esperado: 500

Acesse também /errors/404.html diretamente no navegador para confirmar que o Alias está funcionando e a página carrega com todos os assets:

curl -o /dev/null -sw "%{http_code}\n" http://exemplo.com.br/errors/404.html
# Esperado: 200