Publicação do portal

Chegamos a etapa final da construção do portal de documentação, a publicação em produção.

Foi uma jornada com muitos aprendizados 😎

• Clonamos o repositório para iniciar a construção do Portal
• Criamos a primeira página
• Disponibilizamos a página no menu
• Evoluímos e criamos as documentações
• Customizamos o Portal
• Criamos os arquivos MDX para a API

---

Evoluindo nessa jornada, aprenderemos como realizar a publicação do Portal em produção, permitindo aos nossos usuários acessarem o conteúdo.

observação

Neste guia, utilizaremos um Azure Agent Pool e um Azure Pipelines Agent da Engenharia. Porém reforçamos que seria importante que o seu time/produto possua estes recursos para automação.

Azure static web app

Para publicação do Portal, utilizamos o recursos SWA da Azure, que permite uma publicação rápida e barata.

dica

Não se preocupe, toda organização do SWA dentro do Portal da Azure é nossa responsabilidade, qualquer necessidade entre em contato (paulo.henrique@ndd.tech).

Automação

Todos os repositórios já possuem um arquivo azure-pipelines.yml configurado para publicação.

Entenda o arquivo:

azure-pipelines.yml

trigger:
  - main # Define que o pipeline será acionado quando houver alterações na branch "main"

pool:
  name: 'nddEngenharia Agent Pool' # Especifica o pool de agentes chamado 'nddEngenharia Agent Pool'
  demands: agent.name -equals agent_02_paulo_henrique # Garante que o pipeline será executado apenas no agente específico 'agent_02_paulo_henrique'
jobs:
  - job: DeployJob
  displayName: "Deploy da aplicação no SWA"
  timeoutInMinutes: 300 # Tempo limite de publicação
  steps:
    - checkout: self # Faz o checkout do próprio repositório para o agente, permitindo acesso ao código

    - task: AzureStaticWebApp@0 # Define uma tarefa para implantar um aplicativo estático no Azure
      displayName: "Publicação do Portal no recurso Azure Static Web App"
      inputs:
          production_branch: 'main' # Branch de produção, qualquer envio de outra branch, será publicado em um ambiente de prévia
          app_location: '/' # Define a raiz do repositório como local do aplicativo
          api_location: 'api' # Define a pasta 'api' como local da API (caso tenha funções serverless)
          output_location: 'build' # Define a pasta 'build' como o diretório de saída da build
          azure_static_web_apps_api_token: $(SWA_DEPLOYMENT_TOKEN) # Usa um token armazenado em variáveis do Azure DevOps para autenticação e implantação
          build_timeout_in_minutes: 300 # Tempo limite de execução do Agent do Azure

Publicar as alterações

Depois de realizar todas as modificações necessárias no portal, como criação de documentação, customização ou até mesmo organização do seu menu lateral, chegou o momento de publicar as suas alterações.

Criar a Pull request

1. Acesse o repositório do portal
2. Você deve estar vendo uma mensagem semelhante a You updated "BRANCH COM AS ALTERAÇÕES" 1m ago
3. Clique em Create a pull request

cuidado

Informações que devem estar selecionadas:

1. O repositório do seu portal
2. A branch com as alterações
3. Novamente o repositório do seu portal
4. A Branch main

4. Termine de preencher a Pull request e clique em Create
5. Clique em Aprove e depois em Complete
   1. Selecione Complete associated work items after merging para finalizar quaisquer work itens linkados
   2. Selecione Delete BRANCH COM AS ALTERAÇÕES after merging para deletar a branch que está sendo unificada
6. Clique em Complete merge

dica

Acesse a documentação oficial da Microsoft para saber mais sobre Pull requests.

Verificar a publicação

informação

É importante salientar, que quanto maior for a sua documentação, mais tempo deve levar para finalizar a publicação.

1. No TFS acesse Pipelines 🚀
2. Selecione o Pipeline do seu produto
3. Clique sobre o Stage que está em execução 🔄
4. Clique sobre Deploy da aplicação no SWA
5. Aqui você poderá observar as etapas da publicação

Acessar o portal

O endereço do portal deve refletir o seu objetivo, por exemplo, se um portal está sendo criado para disponibilizar a documentação para desenvolvedores (API), a URL deve ter o sub domínio developer ou dev seguido pelo domínio principal do produto. Por exemplo, o endereço do portal de desenvolvedor do NDD Elog é developer.nddelog.com.

observação

A configuração de DNS é realizada pela engenharia, confira os portais disponíveis:

Produto	Endereço
NDD Elog	developer.nddelog.com
NDD Orbix	dev.nddorbix.com

Se você precisar criar um portal de documentação voltado para outro público que não seja desenvolvedores, entre em contato conosco.

---

Suporte

Qualquer necessidade você pode contar conosco, entre em contato pelo teams ou e-mail: paulo.henrique@ndd.tech.