Receita: usar o AWS S3 localmente para desenvolvimento

O serviço S3 da AWS é uma das melhores, mais baratas e mais populares soluções para armazenamento de arquivos na nuvem. Mas e se em desenvolvimento você precisar trabalhar offline ou, melhor ainda, quiser reduzir o seu custo mensal com a AWS enquanto estiver programando? Esta receita resolve estes problemas.

Ingredientes desta receita

• Docker
• S3 Ninja - estamos usando aqui seu último release que é o 6.4
• Java - mas pode ser substituído pela linguagem de sua preferência
• SDK da AWS para o Java - usamos a versão 2.11.2 - mas você pode fazer adaptações fáceis para seu ambiente caso não seja o Java
• Linux - mas pode ser substituído por Windows ou MacOS

Ingrediente principal: S3 Ninja

O S3 Ninja implementa as APIs de manutenção de objetos ("arquivos") providas pelo S3, sendo assim você conseguirá facilmente simular nele operações de obtenção, escrita e remoção de objetos.

Atenção: observe que não há aqui suporte para a manutenção de buckets. Para que seu ambiente de desenvolvimento esteja completo será necessário que estes buckets já existam no S3 Ninja. Há duas maneiras de se fazer isto: a primeira é usando a interface web que a ferramenta promove, manualmente, por tanto.

A segunda forma é usando Docker, que é bem melhor e já automatiza esta tarefa pra você, evitando com isto o trabalho manual. Vou te ensinar como fazer isto, é bem simples.

Não envenene seus convidados

Apesar do S3 Ninja funcionar tal como quem emula ele não passa de um mock, e um mock muito limitado. Você só consegue interagir com objetos aqui.

S3 Ninja não é escalável, não não é seguro, não é robusto. É apenas o que se propõe ser: um mock para que você consiga simular o S3 no seu ambiente de desenvolvimento ou testes automatizados. Não use em produção e não conte com ele como um componente de alta qualidade.

Primeiro passo: instalando o S3 Ninja

Eis algo que era muito mais fácil de ser feito no passado, então preste muita atenção a este ponto.

A instalação do S3 Ninja hoje se dá a partir do Docker. Se você clicar no link "Download" do site oficial do projeto, será inclusive direcionado para o Docker Hub.

Infelizmente se você tentar executar a imagem provida no link de download acima mencionado talvez não consiga, tal como pode ser visto no print a seguir:

Por quê? Por quê?? Por quê??? Simples: por que no momento da escrita desta receita não existia uma imagem com a versão "latest". Durante a escrita deste post a última versão era a 6.4. Sendo assim, se você executasse o comando abaixo, funcionaria.

docker pull scireum/s3-ninja:6.4

Mas não basta isto: você também irá querer iniciar o S3 Ninja com todos os buckets já criados, certo? Infelizmente na documentação você não encontrará nada lhe ensinando a fazer isto. Então resolvi te poupar tempo aqui. Segue um arquivo Dockerfile customizado. Modifique as instruções "mkdir" para criar todos os buckets que você precisa.

FROM scireum/s3-ninja:6.4
USER sirius

# Inclua todos os buckets que precisa no comando a seguir

CMD mkdir -p /home/sirius/data/seu_primeiro_bucket && \
    mkdir -p /home/sirius/data/seu_segundo_bucket && \
    /home/sirius/run.sh

# O terceiro ponto irá iniciar o processo do S3 Ninja

Caso não saiba o que fazer com este arquivo Dockerfile, crie um arquivo com este nome em um diretório qualquer em seu computador e, neste diretório, execute o seguinte comando:

docker build --tag=s3ninja-itexto:latest .

Isto irá criar uma imagem chamada s3ninja-itexto. O próximo passo consiste em executar seu container. Caso não saiba como fazê-lo, segue um exemplo:

docker run -p 9444:9000 s3ninja-itexto:latest

Voilá: note que estamos direcionando a saída da porta 9000 (do container) para a 9444 do host. Para testar sua instalação abra seu browser e acesse este endereço: http://localhost:9444/ui . Você verá uma página similar à exposta a seguir:

Observe que o Access Key e Secret Key são criados por padrão e apresentados no painel esquerdo desta interface. Guarde esta informação.

Por esta interface você pode criar novos buckets, incluir arquivos em seu interior e verificar quais endpoints da API do S3 estão implementados no S3 Ninja. Pode ser muito útil!

Quer os arquivos de referência? Criei um repositório no Github contendo inclusive um arquivo do Docker Compose pra você. Basta clicar neste link.

Aplicando em seu código fonte

Aplicável a qualquer ambiente de desenvolvimento

Você precisará de três informações apenas:

• Access Key e Secret Key - você o obtém na página pública do S3 Ninja - http://localhost:9444/ui . Boa notícia: estas informações não mudam, então você pode aplicá-las em sua configuração de dev/teste. (não falei que não era seguro o S3 Ninja???)
• Endpoint de requisições - a AWS fornece endpoints padrão de requisições para o S3, mas também a possibilidade de você poder usar endpoints alternativos justamente pra situações muito específicas como esta. O endpoint do S3 Ninja contra o qual todas as requisições deverão ser feitas é o http://localhost:9444/s3

O S3 Ninja vai ignorar qualquer região da AWS e também não vai aplicar ACLs tal como o serviço original, leve isto em consideração. Consulte sua ferramenta de desenvolvimento para que possa realizar esta integração.

Exemplo em Java

Se você não programa em Java, leia mesmo assim pois há um detalhe importante ali.

Tudo o que você precisará fazer é customizar o cliente S3 provido pelo SDK provido pela AWS. Em nosso exemplo iremos usar a versão 2.11.2 desta biblioteca. Leve em consideração que esperamos que você já saiba usar esta biblioteca. Vamos expor aqui apenas como usar junto com o S3 Ninja.

Veja o exemplo a seguir escrito em Java no qual instanciamos o cliente S3 usando o SDK da AWS.

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;


// observe o exemplo com atenção. Se houver a configuração
// do endpoint, é por que estamos usando o S3 Ninja
// claro: pode haver variações, isto é apenas
// um exemplo!

public S3Client getS3Client() {
  String url = "http://localhost:9444/s3");
  S3Client result = S3Client.builder()
               .region(qualquerUma)
               .credentialsProvider(oQueSeAplica)
                // A mágica acontece aqui
               .endpointOverride(URI.create(endpoint))
            // O detalhe da maldade
             serviceConfiguration(
              S3Configuration.builder()
               .chunkedEncodingEnabled(false).build()
               )
               .build();
  return result;
}

O primeiro detalhe é o uso do endpoint customizado. A maldade está no detalhe: a opção "Chunked Encoding". Fizemos isto por que em versões mais antigas do S3 Ninja esta funcionalidade não estava implementada. Sua função consiste em validar o conteúdo recebido pelo S3.

As Deliciosas Receitas da itexto

Esta é mais uma receita do nosso livro que estamos tornando pública. O objetivo é te dar um pontapé inicial para resolver problemas comuns em seu dia a dia no desenvolvimento de software. Claro que há outras alternativas e modos de se resolver o mesmo problema (até melhores!). Caso tenha alguma sugestão, por favor, compartilhe conosco!

Quer escrever seu próprio livro de receitas? Mostramos para você como criamos o nosso e lhe trazemos diversas dicas neste post para te ajudar neste processo. Leia mais clicando aqui!

Tomara que esta receita torne seu dia a dia um pouco melhor. Até a próxima!