% -*- mode: noweb; noweb-default-code-mode: lisp-mode; -*- \documentclass[a4paper,11pt]{article} \usepackage[text={6.75in,10in},centering]{geometry} \usepackage{lipsum} \usepackage{graphicx} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{csquotes} \usepackage[brazil]{babel} \usepackage{etoolbox} \AtBeginEnvironment{quote}{\small} \AtBeginEnvironment{verbatim}{\small} %% \usepackage[backend=biber]{biblatex} %% \addbibresource{refs.bib} %% \renewcommand{\cite}{\parencite} \usepackage[hyperref]{xcolor} \usepackage[colorlinks=true,citecolor=]{hyperref} % linkcolor=red \usepackage{amsmath,amsthm,amssymb} \allowdisplaybreaks \usepackage{lmodern} \usepackage{noweb} \noweboptions{brazil,longchunks,smallcode} \DeclareMathOperator{\mdc}{mdc} \DeclareMathOperator{\gcdext}{gcdext} \DeclareMathOperator{\remainder}{remainder} \DeclareMathOperator{\quotient}{quotient} \DeclareMathOperator{\diff}{diff} \def\nwendcode{\endtrivlist \endgroup} \let\nwdocspar=\par %% Popular names. \newcommand{\lxxp}{{\em loop}} \newcommand{\Lp}{{\tt LOOP}} \newcommand{\lp}{\Lp} \newcommand{\bug}{{\em bug}} \newcommand{\symlink}{{\em symbolic link}} \newcommand{\symlinks}{\symlink s} \newcommand{\etc}{{\em et cetera}} \newcommand{\til}{\textasciitilde} \newcommand{\ezmlm}{{\tt ezmlm}} \newcommand{\qmail}{{\tt qmail}} \newcommand{\git}{{\tt git}} \newcommand{\fg}{{\tt forgejo}} \title{Manual da Antártida} \date{Dezembro 2024} \begin{document} \fontfamily{cmr}\selectfont \maketitle \setlength{\parskip}{5pt} %\setlength{\parindent}{0pt} \section{Publicação de código-fonte} Usamos o \fg\ como publicador web dos nossos \href{https://git.antartida.xyz}{repositórios}. Pra você dirigir o \fg, você precisa usar a conta \git, ou seja, peça {\tt su - git} ao dono da casa, Charlie Root. Dizendo {\tt forgejo help}, você obtém informação como \begin{verbatim} DEFAULT CONFIGURATION: AppPath: /usr/local/sbin/forgejo WorkPath: /usr/local/share/forgejo CustomPath: /usr/local/etc/forgejo ConfigFile: /usr/local/etc/forgejo/conf/app.ini \end{verbatim} \noindent{\bf Como customizar o site}? O \fg\ olha pra ver se existe algum template customizado que substitua um dos templates padrão; se houver, ele substitui; se não, não. Pra substituir {\em templates}, copie-os do código-fonte pro {\tt CustomPath/templates}. Por exemplo, pra alterar o código-fonte do template home.tmpl, copie o home.tmpl que você encontra no código-fonte pra {\tt CustomPath/templates/home.tmpl}. (Já fizemos isso, então você já encontrará o {\tt home.tmpl} por lá.) Fizemos uma customização que foi levar o usuário da página {\em home} direto pra página {\tt explore/repos}. Em outras palavras, evitamos a inútil página principal e levamos o visitante diretamente ao que temos disponível. No modelo {\tt templates/base/head.tmpl} você encontra as tags {\tt html, meta} {\em et cetera}. % \begin{verbatim} {{if eq .TemplateName "home"}} {{end}} \end{verbatim} % A linguagem usada aí é {\em go templates}. O \fg\ é escrito em Go. O ideal seria fazer o redirecionamento direto no cabeçalho HTTP, mas não sei como reprogramar o \fg\ pra isso. Ah, na verdade a gente usa o {\tt nginx} como {\em frontend} pro \fg, então só precisamos fazer o redirecionamento no {\tt nginx} mesmo. Faz lá---tarefa pra você! Fiz a tarefa. Não confie em mim quanto a falar a língua do {\tt nginx}, mas me pareceu simples o construtor {\tt rewrite}. Infiro que a expressão é comparada apenas contra o {\tt path} de uma URL e não contra a URL toda. Por exemplo, a URL {\tt /?hello} também é redirecionada pra {\tt /explore/repos}, como gostaríamos que fosse. % \begin{verbatim} location / { rewrite ^/$ /explore/repos redirect; client_max_body_size 512M; proxy_pass http://forgejo; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } \end{verbatim} \noindent{\bf Onde encontrar o código-fonte}? Use o {\tt ports}. Vá até {\tt /usr/ports/www/forgejo}. Diga {\tt make fetch} pra baixar o código-fonte. Pronto. Agora navegue pelos novos arquivos que apareceram e você se encontrará. Note que instalamos o \fg\ pelo {\tt pkg} e não pelo {\tt ports}. \undef\pib \newcommand{\pib}{{\tt public-inbox}} \newcommand{\ml}{{\em mailing list}} \newcommand{\mls}{\ml{}{\em s}} \undef\path\newcommand{\path}{{\em path}} \section{Arquivos \pib} O software \pib\ é um arquivador de \mls. A documentação disponível sobre o \pib\ é essencialmente um conjunto de referências. Não há um tutorial com passos para leigos---é a vida. Ele usa o git como base de dados, ou seja, o arquivo da \ml\ em si é um repositório git. Assim, você obtém o arquivo fazendo um clone. Por exemplo, clonemos a \ml\ do próprio \pib. \begin{verbatim} %public-inbox-clone https://public-inbox.org/meta/ [...] # /usr/local/bin/git clone --mirror https://public-inbox.org/meta meta Cloning into bare repository 'meta'... remote: Enumerating objects: 39480, done. remote: Counting objects: 100% (1262/1262), done. remote: Compressing objects: 100% (1262/1262), done. remote: Total 39480 (delta 495), reused 0 (delta 0), pack-reused 38218 Receiving objects: 100% (39480/39480), 22.37 MiB | 817.00 KiB/s, done. Resolving deltas: 100% (20326/20326), done. [...] # /usr/local/bin/git --git-dir=meta show-ref # mirrored https://public-inbox.org/meta/ => meta \end{verbatim} Diga {\tt git log} em {\tt meta} e você verá cada messagem adiciona à lista. Tem um {\tt Makefile} lá dentro que vale a pena ser lido. Ele automatiza uma série de operações que estudaremos aqui. Por exemplo, pra obter novas mensagens do repositório git que você clonou, basta dizer {\tt make fetch}. Se você quiser de fato incorporar as novas adições, você diz {\tt make update}. Leia o {\tt Makefile} pra ver que comandos \pib\ executa em cada {\tt target}. Então agora você já sabe como manter seu arquivo atualizado---peça ao {\tt cron} pra fazer um {\em update} periódico. É um jeito diferente de pensar em \mls. Em vez de você se inscrever numa, você simplesmente copia o arquivo dela e lê o arquivo. Quando quiser atualizar seu arquivo, atualiza e continua a leitura. É um jeito mais inteligente. Inscrever-se numa \ml\ só faz sentido quando você quer participar dela de forma bem completa---ler todas as mensagens, responder cada uma com atenção \etc. Note que o \pib\ tem evoluído. Existem agora duas versões de arquivos, um chamado {\tt v1 public-inbox} e um mais novo chamado {\tt v2}. Essa \ml\ que você acabou de clonar é {\tt v1}. Pra mais informações, veja {\tt public-inbox-v1-format(5)}. \noindent{\bf Como expor seu arquivo ao público via HTTP}? Antes de pensar em expor, é preciso informá-lo ao \pib. Você vai criar um arquivo de configuração em {\tt \til/.public-inbox/config}. Eis o meu como exemplo, mas não crie esse arquivo de configuração, não---ele pode deve ser criado pelo programa {\tt public-inbox-init}. % \begin{verbatim} [publicinbox "meta"] address = meta@public-inbox.org url = https://public-inbox.org/meta inboxdir = /usr/home/dbastos/inbox/meta newsgroup = inbox.comp.mail.public-inbox.meta \end{verbatim} Eis o que disse a meu shell pra obter essa configuração: % \begin{verbatim} public-inbox-init -V1 --ng inbox.comp.mail.public-inbox.meta \ meta ./meta https://public-inbox.org/meta \ meta@public-inbox.org \end{verbatim} Agora você já poderia executar o servidor web e assistir o arquivo na web. Faça isso. Execute o {\tt public-inbox-httpd}, que vai ouvir na porta 8080 por padrão, e você verá o arquivo se estendendo página web agora no seu navegador. Vá até o fim da página e clique em {\tt topics (new)}. Você receberá a mensagem ``[o]verview is not available for this public-inbox''. Significa que você não tem um índice pra navegar melhor por essa \ml. Crie o índice dizendo {\tt public-inbox-index meta}, sendo {\tt meta} o diretório que contém seu arquivo, ou seja, seu repositório git. Criar o índice leva um tempo se a \ml\ é grande e a {\tt meta} não é muito pequena, além de crescer com o tempo. Criado o índice, diga {\tt public-inbox-httpd} a seu shell e observe o servidor HTTP iniciar. Visite agora o endereço do seu computador com \path\ {\tt /} na porta 8080---observe o shell pra obter a porta correta---e use o protocolo HTTP e não HTTPS. Ele vai dizer ``{\tt no inboxes, yet}''. Não sei por que ele não exibe uma lista de todas as suas \mls. Mas ignora isso. Visite o \path\ {\tt /meta} e você verá sua \ml, agora indexada. Parabéns. Você já sabe clonar e expor seu arquivo para o mundo. Seu próximo passo é aprender a construir uma \ml\ sua, uma original. Pra isso você precisa saber construir \ml\ usando o \ezmlm. Como exemplo, construi uma \ml\ chamada {\tt dbastos-testlist}. Cada mensagem endereçada a {\tt dbastos-testlist@antartida.xyz} invoca os programas programados em {\tt \til{}dbastos/.qmail-testlist}. Eis o meu: % \begin{verbatim} $ cat ~/.qmail-testlist |/usr/local/bin/ezmlm/ezmlm-reject |/usr/local/bin/ezmlm/ezmlm-send '/usr/home/dbastos/list/testlist' |/usr/local/bin/ezmlm/ezmlm-warn '/usr/home/dbastos/list/testlist' || exit 0 |env ORIGINAL_RECIPIENT=dbastos-testlist@antartida.xyz \ /usr/local/bin/public-inbox-mda --no-precheck \end{verbatim} % Em outras palavras, quando o qmail recebe uma mensagem pra {\tt dbastos-testlist@antartida.xyz}, ele invoca cada um desses programas aí. O último deles é o MDA do \pib. MDA significa {\em mail delivery agent}. O {\tt public-inbox-mda} espera uma variável chamada {\tt ORIGINAL\_RECIPIENT}. Servidores como Postfix já criam essa variável, o que entrega o viés do autor do \pib\ pelo Postfix. Como usamos o qmail, precisamos criar essa variável nós mesmo. Não sei exatamente que conteúdo ela deveria ter---adivinhei que seria o endereço da própria lista e fui em frente---com sucesso. Veja {\tt public-inbox-mda(1)} pra mais informações. \noindent{\bf Como expor seu arquivo ao público via NNTP}? Veja {\tt public-inbox-nntpd}. Por exemplo: % \begin{verbatim} $ public-inbox-nntpd -l nntp://0.0.0.0:1024 # bound nntp://0.0.0.0:1024 \end{verbatim} % Aí está seu servidor NNTP em ação. Em seguida, simule um cliente usando {\tt telnet}: \begin{verbatim} $ telnet 0 1024 Trying 0.0.0.0... Connected to 0. Escape character is '^]'. 201 antartida.xyz ready - post via email list 215 list of newsgroups follows inbox.comp.mail.public-inbox.meta 9869 1 n inbox.people.dbastos-testlist 5 1 n . quit 205 closing connection - goodbye! Connection closed by foreign host. \end{verbatim} % Aí estão seus arquivos servidos via NNTP. O \pib\ também é capaz de servi-los via IMAP e POP3 se algum dia você desejá-los. %% \section*{Index of chunks} %% \nowebchunks %% %% \section*{Index of names} %% \nowebindex \end{document}