Skip to content

INSTALL.pt-br.md

Latest commit

 

History

History
282 lines (189 loc) · 19.7 KB

INSTALL.pt-br.md

File metadata and controls

282 lines (189 loc) · 19.7 KB

Índice

Instalando e Implantando

Abordagem Recomendada

A abordagem recomendada para usar o al-folio é criar primeiro seu próprio site utilizando o template com o mínimo de alterações possível e, somente quando estiver em funcionamento, personalizá-lo como você desejar. Dessa forma, fica mais fácil identificar o que pode causar um eventual problema em caso de bug. Os passos mínimos exigidos para criar seu próprio site são (tutorial em vídeo aqui):

  1. Crie um novo repositório utilizando este template. Para isso, clique em Use this template -> Create a new repository acima da lista de arquivos. Se você planeja enviar seu site para <seu-usuario-github>.github.io, note que o nome do seu repositório ⚠️ DEVE SER ⚠️ <seu-usuario-github>.github.io ou <seu-orgname-github>.github.io, conforme indicado na documentação do GitHub Pages.

  2. Neste novo repositório, vá em Settings -> Actions -> General -> Workflow permissions e conceda Read and write permissions ao GitHub Actions.

  3. Abra o arquivo _config.yml, defina url para https://<seu-usuario-github>.github.io e deixe baseurl vazio (não o apague), como em baseurl:.

  4. Aguarde até que a action do GitHub com o subtítulo Deploy site termine (verifique a aba Actions do repositório), o que leva em média ~4 min. Agora, além da branch main, seu repositório terá uma nova branch gh-pages gerada.

  5. Por fim, na página do repositório, vá para Settings -> Pages -> Build and deployment, certifique-se de que a opção Source esteja definida como Deploy from a branch e escolha a branch gh-pages (não a main).

  6. Aguarde até que a action do GitHub pages-build-deployment termine (verifique a aba Actions do repositório), o que leva em torno de ~45s, e então navegue para https://<seu-usuario-github>.github.io no seu navegador. Neste ponto, você deverá ver uma cópia do site demo do tema.

    Após tudo estar configurado, você pode clonar (baixar) o repositório para sua máquina e começar a personalizá-lo. Para isso, execute os seguintes comandos:

$ git clone git@github.com:<seu-usuario>/<nome-do-seu-repositório>.git

A partir da versão v0.3.5, o al-folio re-implantará automaticamente sua página da web sempre que você enviar novas alterações para o seu repositório! ✨

Configuração local no Windows

Se você está usando o Windows, é altamente recomendado usar o Windows Subsystem for Linux (WSL), que é uma camada de compatibilidade para rodar Linux no Windows. Você pode seguir essas instruções para instalar o WSL e o Ubuntu na sua máquina. Você só precisa seguir até o passo 4 do tutorial (não é necessário habilitar o systemd opcional nem os aplicativos gráficos), e então pode seguir as instruções abaixo para instalar o Docker. Também é possível instalar o Docker nativamente no Windows, mas ele tem apresentado alguns problemas, como pode ser visto em #1540 e #2007.

Configuração local usando Docker (Recomendado)

Usar o Docker para instalar o Jekyll e as dependências do Ruby é a maneira mais fácil.

Você precisa seguir os seguintes passos para fazer o al-folio funcionar na sua máquina local:

  • Primeiro, instale o docker e o docker-compose.
  • Por fim, execute o seguinte comando que irá baixar a imagem pré-construída mais recente do DockerHub e executará seu site.
$ docker compose pull
$ docker compose up

Observe que, quando você executá-lo pela primeira vez, ele fará o download de uma imagem docker de cerca de 400MB. Para ver o template em execução, abra seu navegador e vá para http://localhost:8080. Você deve ver uma cópia do site demo do tema.

Agora, sinta-se à vontade para personalizar o tema como quiser (não se esqueça de mudar o nome!). Além disso, suas alterações devem ser renderizadas automaticamente em tempo real (ou talvez após alguns segundos).

Beta: Você também pode usar a imagem docker reduzida com um tamanho abaixo de 100MB e a mesma funcionalidade. Basta usar docker compose -f docker-compose-slim.yml up

Crie sua própria imagem Docker

Nota: essa abordagem só é necessária se você quiser construir uma versão mais antiga ou muito personalizada do multi-language-al-folio.

Crie e execute uma nova imagem docker usando:

$ docker compose up --build

Se você quiser atualizar o jekyll, instalar novos pacotes ruby, etc., tudo o que você precisa fazer é construir a imagem novamente usando o argumento --force-recreate no final do comando anterior! Isso fará o download do Ruby e do Jekyll e instalará todos os pacotes Ruby novamente do zero.

Se você quiser usar uma versão específica do docker, pode fazê-lo alterando a tag latest para sua_versão no docker-compose.yaml. Por exemplo, você pode ter criado seu site na versão v0.10.0 e deseja permanecer com essa versão.

Encontrou erros na imagem Docker?

Às vezes, pode haver alguns bugs na imagem docker atual. Pode ser um erro de versão ou qualquer outra coisa. Se você quiser depurar e resolver facilmente o problema por conta própria, pode seguir os passos a seguir:

docker compose up -d
docker compose logs

Então você pode ver o bug! Você pode entrar no contêiner com este comando:

docker compose exec -it jekyll /bin/bash

Então você pode executar o script:

./bin/entry_point.sh

Você pode ver problemas de dependência de pacote ou algo que não está disponível. Você pode corrigir isso agora usando

bundle install
./bin/entry_point.sh

Na maioria das vezes, isso resolverá o problema, mas não deveria realmente acontecer. Portanto, por favor, abra um relatório de bug para nós.

Configuração local com Containers de Desenvolvimento

O al-folio suporta Containers de Desenvolvimento. Por exemplo, quando você abre o repositório com o Visual Studio Code (VSCode), ele solicita que você instale a extensão necessária e instala automaticamente tudo o que é necessário.

Configuração Local (Legado, não mais suportado)

Para um tutorial prático de como rodar o multi-language-al-folio localmente sem usar o Docker, confira este blog interessante de um dos membros da comunidade!

Assumindo que você tenha Ruby e Bundler instalados no seu sistema (dica: para facilitar o gerenciamento de gems do Ruby, considere usar rbenv), e também Python e pip (dica: para facilitar o gerenciamento de pacotes Python, considere usar um ambiente virtual, como venv ou conda).

$ bundle install
# assumindo que pip é o seu gerenciador de pacotes Python
$ pip install jupyter
$ bundle exec jekyll serve

Para ver o template em execução, abra seu navegador e vá para http://localhost:4000. Você deverá ver uma cópia do site demo do tema. Agora, sinta-se à vontade para personalizar o tema como quiser. Após terminar, lembre-se de commitar suas alterações finais.

Implantação

Implantar seu site no GitHub Pages é a opção mais popular. A partir da versão v0.3.5, o al-folio re-implantará automaticamente sua página da web sempre que você enviar novas alterações para o seu repositório branch principal! ✨

Para páginas pessoais e de organizações

  1. O nome do seu repositório DEVE SER <seu-usuario-github>.github.io ou <sua-organizacao-github>.github.io.
  2. No arquivo _config.yml, defina url como https://<seu-usuario-github>.github.io e deixe baseurl vazio.
  3. Configure a implantação automática da sua página (veja as instruções abaixo).
  4. Faça alterações na sua branch principal, faça o commit e envie!
  5. Após a implantação, a página estará disponível em <seu-usuario-github>.github.io.

Para páginas de projetos

  1. No arquivo _config.yml, defina url como https://<seu-usuario-github>.github.io e baseurl como /<nome-do-seu-repositorio>/.
  2. Configure a implantação automática da sua página (veja as instruções abaixo).
  3. Faça alterações na sua branch principal, faça o commit e envie!
  4. Após a implantação, a página estará disponível em <seu-usuario-github>.github.io/<nome-do-seu-repositorio>/.

Habilitando implantação automática

  1. Clique na aba Actions e Habilite o GitHub Actions; não se preocupe em criar workflows, pois tudo já está configurado para você.
  2. Vá para Settings -> Actions -> General -> Workflow permissions e conceda Read and write permissions ao GitHub Actions.
  3. Faça quaisquer outras alterações na sua página, faça o commit e envie para a branch principal. Isso acionará automaticamente a ação Deploy.
  4. Aguarde alguns minutos e deixe a ação ser concluída. Você pode acompanhar o progresso na aba Actions. Se concluído com sucesso, além da branch main, seu repositório agora terá uma nova branch gh-pages criada. Não toque nesta branch!
  5. Finalmente, nas Configurações do seu repositório, na seção Pages, defina a branch como gh-pages (NÃO como main). Para mais detalhes, veja Configurando uma fonte de publicação para seu site GitHub Pages.

Se você mantém seu site em outra branch, abra .github/workflows/deploy.yml na branch onde você mantém seu site e altere on->push->branches e on->pull_request->branches para a branch onde você mantém seu site. Isso acionará a ação em pulls/pushes nessa branch. A ação então implantará o site na branch de onde foi acionada.

Implantação manual no GitHub Pages

Se você precisar reimplantar manualmente seu site no GitHub Pages, vá para a aba Actions, clique em "Deploy" na barra lateral esquerda e depois em "Run workflow".

Implantar no Netlify

  1. Use este template -> Crie um novo repositório.
  2. Netlify: Adicione um novo site -> Importe um projeto existente -> GitHub e dê acesso ao Netlify ao repositório que você acabou de criar.
  3. Netlify: Nas configurações de implantação
  • Defina Branch to deploy como main
  • Base directory deve estar vazia
  • Defina Build command como sed -i "s/^\(baseurl: \).*$/baseurl:/" _config.yml && bundle exec jekyll build
  • Defina Publish directory como _site
  1. Netlify: Adicione as seguintes duas variáveis de ambiente
  • Chave Valor
    JEKYLL_ENV production
    RUBY_VERSION defina como a versão do Ruby encontrada em .github/workflows/deploy.yml (por exemplo, 3.3.5)
  1. Netlify: Clique em Deploy e aguarde o site ser publicado. Se você quiser usar seu próprio nome de domínio, siga os passos nesta documentação.

Implantação em outro servidor de hospedagem (que não seja o GitHub Pages)

Se você decidir não usar o GitHub Pages e hospedar sua página em outro lugar, simplesmente execute:

$ bundle exec jekyll build

Isso irá (re)gerar a página estática na pasta _site/. Depois, basta copiar o conteúdo do diretório _site/ para o servidor de hospedagem.

Se você também quiser remover classes CSS não utilizadas do seu arquivo, execute:

$ purgecss -c purgecss.config.js

Isso substituirá os arquivos CSS na pasta _site/assets/css/ pelos arquivos CSS purgados.

Nota: Certifique-se de configurar corretamente os campos url e baseurl no arquivo _config.yml antes de construir a página. Se você estiver implantando sua página em seu-dominio.com/seu-projeto/, você deve definir url: seu-dominio.com e baseurl: /seu-projeto/. Se você estiver implantando diretamente em seu-dominio.com, deixe baseurl vazio, não o exclua.

Implantação em um repositório separado (somente para usuários avançados)

Nota: Não tente usar este método a menos que você saiba o que está fazendo (certifique-se de estar familiarizado com fontes de publicação). Esta abordagem permite ter o código-fonte do site em um repositório e a versão implantada em outro repositório.

Vamos supor que a fonte de publicação do seu site seja um subdiretório publishing-source de um repositório versionado com git clonado em $HOME/repo/. Para um site de usuário, isso pode ser algo como $HOME/<usuario>.github.io.

Primeiramente, no diretório do repositório de implantação, faça checkout da branch git que hospeda sua fonte de publicação.

Depois, no diretório das fontes do site (geralmente o clone do fork do multi-language-al-folio):

$ bundle exec jekyll build --destination $HOME/repo/publishing-source

Isso instruirá o jekyll a implantar o site em $HOME/repo/publishing-source.

Nota: O Jekyll limpará $HOME/repo/publishing-source antes de construir!

A citação abaixo é retirada diretamente da documentação de configuração do jekyll:

Pastas de destino são limpas nas construções do site

O conteúdo de <destination> é automaticamente limpo, por padrão, quando o site é construído. Arquivos ou pastas que não são criados pelo seu site serão removidos. Alguns arquivos podem ser mantidos especificando-os dentro da diretiva de configuração <keep_files>.

Não use um local importante para <destination>; em vez disso, use-o como uma área de preparação e copie os arquivos de lá para o seu servidor web.

Se $HOME/repo/publishing-source contiver arquivos que você deseja que o jekyll deixe intocados, especifique-os em keep_files no _config.yml. Na configuração padrão, o multi-language-al-folio copiará o README.md do nível superior para a fonte de publicação. Se você quiser alterar esse comportamento, adicione README.md em exclude no _config.yml.

Nota: Não execute jekyll clean no repositório da fonte de publicação, pois isso resultará na exclusão de todo o diretório, independentemente do conteúdo de keep_files no _config.yml.

Mantendo Dependências

O al-folio usa o Bundler (um gerenciador de dependências do Ruby) para acompanhar todos os pacotes Ruby (chamados de "gems") necessários para executar o Jekyll e seus plugins. Com o tempo, esses pacotes podem receber atualizações que incluem correções de bugs, patches de segurança e novos recursos.

Atualizando o bundler

A ferramenta bundler em si deve ser mantida atualizada. Para atualizar o bundler para a versão mais recente, execute:

$ bundle update --bundler

Atualizando todas as dependências

Para atualizar todos os gems do Ruby para suas versões compatíveis mais recentes (conforme especificado em seu Gemfile), execute:

$ bundle update --all

Após atualizar as dependências, teste seu site localmente para garantir que tudo ainda funciona corretamente:

  • Se usar Docker: docker compose up
  • Se usar configuração local: bundle exec jekyll serve

Nota: As atualizações de dependências podem ocasionalmente introduzir mudanças que quebram a compatibilidade. Se seu site falhar após a atualização, consulte o FAQ para solução de problemas, ou reverta para a versão anterior com bundle lock --add-platform ruby e git checkout Gemfile.lock.

Atualizando de uma versão anterior

Se você instalou o multi-language-al-folio conforme descrito acima, pode atualizar manualmente seu código seguindo os passos abaixo:

# Assumindo que o diretório atual é <nome-do-seu-repositório>
$ git remote add upstream https://github.com/george-gca/multi-language-al-folio.git
$ git fetch upstream
$ git rebase v1.16.2

Se você personalizou extensivamente uma versão anterior, pode ser mais complicado atualizar. Você ainda pode seguir os passos acima, mas o git rebase pode resultar em conflitos de merge que precisarão ser resolvidos. Consulte o manual do git rebase e como resolver conflitos para mais informações. Se o rebase for muito complicado, recomendamos reinstalar a nova versão do tema do zero e portar manualmente seu conteúdo e alterações da versão anterior. Você pode usar ferramentas como meld ou winmerge para ajudar nesse processo.