285 lines
11 KiB
Text
285 lines
11 KiB
Text
% -*- 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"}}
|
|
<meta http-equiv="refresh" content="0; url=https://git.antartida.xyz/explore/repos">
|
|
{{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}
|