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
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:
- O bucket S3 como origem e o OAC como mecanismo de acesso.
- O certificado ACM emitido em
us-east-1e os aliases do domínio. index.htmlcomo documento raiz.- Redireccionamento de HTTP para HTTPS.
- Métodos permitidos apenas
GETeHEADpara um site estático simples. - Compressão e uma política de cache adequada ao conteúdo.
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.
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:
AWS_ROLE_ARN— ARN da IAM Role de deploy.AWS_REGION— região do bucket S3.S3_BUCKET— nome do bucket.CLOUDFRONT_DISTRIBUTION_ID— ID da distribuição.
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
- Verificar se o certificado ACM está
ISSUED. - Espera que a distribuição CloudFront fique
Deployed. - Publicar o site e verificar se
index.htmlexiste no bucket. - Testar primeiro o hostname
cloudfront.net, antes de alterar o DNS. - Em caso de erro 403, verificar a policy do bucket e a associação do OAC.
- Depois da migração, verificar os registos DNS autoritativos e testar o domínio e o redireccionamento.
- 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.
- Manter o S3 privado e o OAC activo.
- Utilizar HTTPS e um certificado ACM renovável por DNS.
- Limita a role OIDC ao repositório e branch de deploy.
- Protege a branch principal e revê alterações ao workflow.
- Utilizar tags de projecto para identificar e controlar os custos dos recursos.
- Ponderar headers de cache diferentes para HTML e assets versionados, conforme a estratégia de publicação.
- Testar a publicação e a invalidação antes de apontar o domínio de 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.