Primeiros Passos
Bem-vindo ao Crystallized Perl — um stack completo e opinativo para construir serviços de internet modernos em Perl: aplicações web, APIs HTTP e workers em background.
O que você vai encontrar aqui
Esta documentação é organizada em quatro seções:
| Seção | Conteúdo |
|---|---|
| Primeiros Passos | Esta seção — visão geral, pré-requisitos e orientação |
| Guias | Tutoriais passo a passo usando a aplicação Stega como referência |
| Stack | Referência rápida por tecnologia — comandos, padrões, armadilhas |
| Decisões (ADRs) | Architectural Decision Records — o porquê de cada escolha |
Para quem é este stack
Este projeto é para desenvolvedores que querem construir serviços de internet em Perl moderno e preferem seguir um stack decidido a avaliar infinitas opções.
Assume-se que você:
- Conhece os fundamentos de Perl (variáveis, referências, módulos)
- Sabe o básico de HTTP e serviços web
- Tem familiaridade com linha de comando e Git
- Conhece Docker (ou quer aprender junto com o stack)
Se você é novo em Perl, o livro Modern Perl é o ponto de partida recomendado antes de seguir os guias.
Pré-requisitos globais
Todos os guias desta documentação partem dos seguintes pré-requisitos:
Ferramentas obrigatórias
| Ferramenta | Versão mínima | Verificação |
|---|---|---|
| Git | 2.40+ | git --version |
| Docker | 24+ | docker --version |
| Docker Compose | v2 (embutido no Docker) | docker compose version |
Perl local (apenas para guias fora de Docker)
Se você preferir rodar Perl diretamente no sistema (sem Docker):
| Plataforma | Ferramenta | Versão |
|---|---|---|
| Linux / macOS | perlbrew | qualquer versão recente |
| Windows | berrybrew | qualquer versão recente |
| Perl instalado | — | 5.42.2 (versão mínima do stack) |
O Guia 1 cobre a instalação passo a passo para cada plataforma.
A aplicação de referência — Stega
Todos os guias e exemplos de código usam a Stega — um sistema de tickets de suporte para produtos de software — como aplicação de referência canônica.
A Stega foi escolhida porque exercita todos os componentes do stack:
- Frontend server-rendered com autenticação Keycloak (OIDC)
- API REST com contrato OpenAPI v3
- PostgreSQL com JSONB, busca full-text e migrations
- Fila local de jobs com Minion (PostgreSQL backend)
- Worker de notificações com RabbitMQ (AMQP 0-9-1)
Você não implementa a Stega do zero nos guias. Os guias usam o repositório
hibex-solutions/crystallized-perl-stega como contexto e focam no aspecto
técnico sendo ensinado. Consulte o ADR-018
para o design completo da aplicação.
Por onde começar
Se você quer seguir a trilha de guias
Siga os guias na ordem numérica — cada um pressupõe o anterior:
- Guia 1 — Ambiente de Desenvolvimento: instala Perl 5.42, Carton e sobe os serviços locais com Docker Compose
- Guia 2 — Estrutura Mínima de Projeto:
cria o esqueleto da Stega com
cpanfile,.gitattributese DEVELOPMENT.md - Guia 3 — Primeira Rota com Mojolicious:
implementa o
GET /healthze a estrutura de controllers da aplicação
Se você quer entender as decisões
Leia as ADRs em ordem crescente, começando pelo ADR-000 (padrão de ADRs) e ADR-004 (Mojolicious).
Se você quer consultar uma tecnologia específica
Vá direto à seção Stack e encontre a página da tecnologia que você precisa.
Princípios que guiam cada decisão
Antes de mergulhar nos guias, vale entender os cinco princípios não negociáveis do stack — eles aparecem em cada ADR:
- Reference-first — toda decisão cita ao menos uma fonte externa autoritativa
- Decision transparency — cada escolha tem uma ADR com motivação e alternativas
- Stack cohesion — este projeto define um stack, não um menu de opções
- Modern Perl — Perl 5.42+ obrigatório; padrões arcaicos são explicitamente proibidos
- Cloud-native first — tudo roda em containers; desenvolvimento local usa Docker Compose