AWS · Infraestrutura · Tutorial

Como publicar um site estático na AWS

S3 privado, CloudFront, HTTPS, domínio próprio e deploy automático com GitHub Actions — uma arquitectura simples, segura e sem servidores para administrar.

Guia prático · Novembro de 2026 · Cerca de 10 minutos de leitura

Neste artigo
  1. A arquitectura
  2. Criar o bucket S3 privado
  3. Certificado HTTPS com ACM
  4. CloudFront e Origin Access Control
  5. Ligar o domínio no Route 53
  6. Deploy automático com GitHub Actions e OIDC
  7. Testes e resolução de problemas
  8. Segurança, operação e custos
  9. Exemplo real: pmcosta.net

Um site estático — HTML, CSS, JavaScript e imagens — não precisa de uma máquina virtual, de um servidor web permanentemente ligado ou de uma aplicação complexa. A AWS disponibiliza os componentes necessários para servir estes ficheiros globalmente, através de uma arquitectura gerida.

Este guia descreve uma implementação em que o S3 guarda os ficheiros sem exposição pública, o CloudFront entrega o conteúdo por HTTPS e o GitHub Actions publica cada alteração. A autenticação entre GitHub e AWS é feita com OIDC, sem guardar chaves de acesso AWS de longa duração no GitHub.

1. A arquitectura

GitHubCódigo e workflow de publicação
GitHub ActionsOIDC e sincronização dos ficheiros
Amazon S3Bucket privado, versionado
Amazon CloudFrontCDN, HTTPS e cache global
ACMCertificado TLS para o domínio
Route 53DNS e aliases para CloudFront

O percurso do visitante é simples: o DNS aponta o domínio para o CloudFront; o CloudFront apresenta o certificado TLS e, quando precisa do ficheiro, acede ao bucket através de um Origin Access Control (OAC). O bucket não precisa de permitir pedidos públicos.

2. Criar o bucket S3 privado

Criar um bucket com um nome globalmente único, na região pretendida. Neste exemplo, a região é eu-west-1. O bucket é uma origem S3 normal, não um endpoint de website estático.

BUCKET="nome-unico-do-bucket"
REGION="eu-west-1"

aws s3api create-bucket \
  --bucket "$BUCKET" \
  --region "$REGION" \
  --create-bucket-configuration LocationConstraint="$REGION"

Activa todas as opções de bloqueio de acesso público, impõe propriedade dos objectos pelo proprietário do bucket, encriptação por omissão e versioning:

aws s3api put-public-access-block \
  --bucket "$BUCKET" \
  --public-access-block-configuration \
  BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

aws s3api put-bucket-ownership-controls \
  --bucket "$BUCKET" \
  --ownership-controls 'Rules=[{ObjectOwnership=BucketOwnerEnforced}]'

aws s3api put-bucket-encryption \
  --bucket "$BUCKET" \
  --server-side-encryption-configuration \
  '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'

aws s3api put-bucket-versioning \
  --bucket "$BUCKET" \
  --versioning-configuration Status=Enabled

É boa prática etiquetar os recursos com uma tag de projecto, por exemplo Project=nome-do-projecto. Não é necessário activar o alojamento de website do S3: o CloudFront usa o endpoint REST do bucket.

3. Pedir o certificado HTTPS no ACM

Para uma distribuição CloudFront, o certificado ACM tem de estar na região us-east-1, mesmo que o bucket esteja noutra região. Pede um certificado para o domínio principal e, se aplicável, para o nome www.

aws acm request-certificate \
  --region us-east-1 \
  --domain-name exemplo.pt \
  --subject-alternative-names www.exemplo.pt \
  --validation-method DNS

Consultar os registos CNAME de validação com describe-certificate e criá-los na zona DNS. Aguardar até o estado do certificado ser ISSUED. Manter os CNAME de validação para permitir a renovação automática do certificado.

4. Criar CloudFront e Origin Access Control

Criar um OAC com tipo de origem S3, assinatura SigV4 e comportamento de assinatura always. Na origem da distribuição, utilizar o endpoint REST regional do bucket e associar o OAC. Não utilizar o endpoint s3-website.

Na distribuição, configura:

Depois de conhecer o ID da distribuição, autoriza apenas essa distribuição a ler objectos do bucket. A policy deve usar o serviço CloudFront como principal, a acção s3:GetObject, o recurso arn:aws:s3:::NOME-DO-BUCKET/* e uma condição AWS:SourceArn com o ARN exacto da distribuição.

Não resolvas erros 403 tornando o bucket público. Verificar primeiro a policy, o OAC, o endpoint de origem e a existência do objecto pedido.

Se quiseres que www.exemplo.pt redireccione para exemplo.pt, ambos os nomes têm de estar cobertos pelo certificado e associados à distribuição. Uma CloudFront Function no evento viewer-request pode devolver um 301 para o domínio canónico, preservando o caminho e a query string.

5. Ligar o domínio no Route 53

Depois de a distribuição ficar Deployed, cria registos Alias A e AAAA na zona hospedada do Route 53, apontando para a distribuição CloudFront. O Hosted Zone ID global usado nos aliases CloudFront é Z2FDTNDATAQYW2.

Se for utilizada uma função de redireccionamento para o nome www, criar também os aliases A e AAAA de www para a mesma distribuição. O redireccionamento acontece na CloudFront Function, não no registo DNS.

Altera apenas os registos necessários. Registos MX, SPF, DKIM, DMARC, VPN e outros subdomínios não devem ser tocados durante a migração do site.

6. Deploy automático com GitHub Actions e OIDC

O objectivo é que cada push para main publique os ficheiros no S3 e invalide a cache CloudFront. Para evitar access keys permanentes, configura o fornecedor OIDC do GitHub na conta AWS e cria uma IAM Role que o workflow possa assumir.

A trust policy da role deve restringir o emissor a token.actions.githubusercontent.com, a audiência a sts.amazonaws.com e o subject ao repositório e branch exactos. O formato tradicional é repo:OWNER/REPO:ref:refs/heads/main. Atenção à evolução do GitHub: repositórios criados a partir de 15 de Julho de 2026, ou que tenham activado os subjects imutáveis, podem emitir um subject que inclui também os IDs numéricos do proprietário e do repositório: repo:OWNER@ORG_ID/REPO@REPO_ID:ref:refs/heads/main. A trust policy tem de corresponder exactamente ao claim emitido pelo repositório. Não uses um subject aberto a todos os repositórios se só um site precisa de publicar.

A policy de permissões da role deve limitar-se ao necessário: listar o bucket, escrever e apagar objectos nesse bucket e criar invalidações apenas na distribuição do site. Não atribuas permissões administrativas gerais.

No repositório GitHub, configura estas variáveis em Settings → Secrets and variables → Actions → Variables:

Um workflow mínimo pode ser assim:

name: Deploy website

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

      - name: Sync website
        run: |
          aws s3 sync . "s3://${{ vars.S3_BUCKET }}" \
            --delete \
            --exclude ".git/*" \
            --exclude ".github/*" \
            --exclude "docs/*" \
            --exclude "README.md"

      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id "${{ vars.CLOUDFRONT_DISTRIBUTION_ID }}" \
            --paths "/*"

O parâmetro --delete remove do bucket ficheiros que já não existem no repositório. A sua utilização deve limitar-se a buckets dedicados ao site e a padrões de exclusão devidamente verificados. Mantém documentação interna fora da publicação.

7. Testes e resolução de problemas

  1. Verificar se o certificado ACM está ISSUED.
  2. Espera que a distribuição CloudFront fique Deployed.
  3. Publicar o site e verificar se index.html existe no bucket.
  4. Testar primeiro o hostname cloudfront.net, antes de alterar o DNS.
  5. Em caso de erro 403, verificar a policy do bucket e a associação do OAC.
  6. Depois da migração, verificar os registos DNS autoritativos e testar o domínio e o redireccionamento.
  7. Se DNS público resolver mas o resolver local devolver NXDOMAIN, investiga a cache negativa do resolver local (por exemplo AdGuard Home/Unbound) antes de alterar novamente o Route 53.

Para testar um domínio antes da propagação DNS, curl --resolve nome:443:IP https://nome/ permite ligar a um IP conhecido mantendo o hostname e o SNI TLS. Para testar o redireccionamento, inspecciona o código HTTP e o cabeçalho Location.

8. Segurança, operação e custos

Esta arquitectura elimina a gestão de servidores, mas não é automaticamente gratuita. O custo depende sobretudo dos pedidos e dados transferidos pelo CloudFront, armazenamento e operações S3, invalidações e eventuais serviços adicionais. Consultar os preços AWS da região e classe de utilização escolhidas antes da entrada em produção.

O resultado é uma plataforma de publicação pequena, escalável e com poucos componentes operacionais: o código vive no Git, o S3 guarda os ficheiros, o CloudFront serve-os e o GitHub Actions automatiza a entrega.