BAOBÁXIA

NA ROTA DOS BAOBÁS

                               .
                              ,d              .   ,
                             aA...             YF^
                              *@@@b          d@P
                                *@@@b,,,,,-d@@P   ,     ,
                    ....a@@@@aa.. *@@V@`;;..,,  ,*,   ,*
                     `V*'  ``*@@B`b b@((bb`@@P*q*@@*"'
                               `*@`9@,(()))*'   `*.   
                                `A@,`@@Y@(;'
                                 (a`@,`@`&@
                                ."@,@`.@(@@
                               (@a.@",@^a.,
                               ,.o..o@ (@o.`
                               (*",.`*@@o`*@,         "Vamos fazer um mundo digital
                              ,',@***@a,,`^*.,                       mais do nosso jeito!"
                              ,&^,@@@@@a,`a.,
                              &`@`,;aaaa @; )@        NPDD/Rede Mocambos
                              c@(.@".;'".@",@@"
                              @@ @",@`.@*`,@@`,
                              @P,@,*@a, ,a@*`,@
                            , *(`*@@a.,*@*`,@*`
                ,;a&*"` .;a@@ *;,'o,`*@@a;@@P`, oo..,,
        ,.;a@@@*"`  ,;a@@*"` , *"`7`,"a,`"*",d) **oo..`""*oo.,
    ,;@@@@@@*`  ,;d@@@@P` ,.@@b *@b`"@a,`"*@@@` ~*o..,`""*oo,."*@a,
    @@@@@@@@b   `*@@@@@;, `'"*@, "*@@a`*@@&;,` ~*o.,, `"@a, `*@b,`*@a
    `"*@@@@@@b.    `"*o@@@@a;,  `"*o,,`` `""*@@@b;.`"*, `@@   `@@;  `*,
       `"*@@@@@@b.     ``*o@@@@@@;,   `"*ooo**'`  ,;o@*  `@    @@@; 
          `"*@@@@@@@b.,     ``"***oo@@oo;,,,,,;;o@@*'` ,;o@    `@@@@,
             `"*@@@@@@@@@b.,,                       ,;o@@@@     @@@@@ 
                `"*@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@P*    ,@@@@@
                        ````````''''''''''''''''''''```  ,...;@@@@P*`
                                                      ```'"""```

Publicado sob GNU/GPLv3.

Introdução

“A ideia nasce da referência do Baobá, árvore que vive milhares de anos e representa simbolicamente a memória coletiva ligada ao território. Baobáxia é a união de baobá com galáxia. Uma galáxia de memórias coletivas locais ligadas ao território. A galáxia liga também com as estrelas, que por sua vez são ligadas a Casa de Cultura Tainã, que em tupi-guarani significa caminho das estrelas. Baobáxia vira bbx, tirando as vocais, que remete ao acrônimo bbs que eram os nos de uma antiga rede de computadores.”

Baobáxia é um sistema de gestão descentralizada de repositórios compartilhados dentro de uma rede denominada rota, a Rota dos Baobás. As instâncias que controlam os repositórios, denominadas Mucuas, que também é o nome do fruto do Baobá, gerenciam os repositórios a partir de uma API de metadados exposta como rest, atuando sobre repositórios sincronizados.

São pontos de atenção do projeto a eficácia no compartilhamento de dados em redes instáveis e de baixa disponibilidade e a eficiência no uso do hardware local visando facilitar o acesso a equipamentos com potencial de serem Mucuas.

Apoio

A partir de dezembro de 2019 o projeto conta com apoio da FAPESP atravez do projeto: Siwazi Rowaihuuze Auwe - rede de informação Xavante: conectividade, gestão de dados e apropriação da internet por povos indígenas. Processo: 18/23094-4

Este projeto foi realizado com apoio da rede de pesquisa Socio-Environmental Knowledge Commons (SEEKCommons), National Science Foundation, #2226425.

Conceitos básicos

A Baobáxia funciona como uma plataforma federada (usuáries se conectam a instâncias diferentes e essas conectam-se entre si) e rizomática (as instâncias funcionam de forma independente e descentralizada). Para além disso, os conceitos próprios da Baobáxia são descritos, tanto em termos leigos quanto técnicos, neste documento.

Instalação

Com essa linea instala uma mucua pronta para produção.

Mocambola: exu e senha: livre

 wget --no-check-certificate https://labmocambos.taina.net.br/npdd/baobaxia-mucua/-/raw/master/install.sh -O install.sh; chmod +x install.sh; ./install.sh

Testado com Debian 12 e Ubuntu 22

Configurando OAUTH

Aqui um exemplo de arquivo .env

OAUTH2_CLIENT_ID = "abcdILNlt1fWdoquaBS9kqpqnZCD1ZLoYtliOcfLEwWrB46bO8Hryawegc4us6Sa"
OAUTH2_CLIENT_SECRET = "1234aT8h2j08iSbVOQA3FhkGiOSxgAqOVpp9JjlFXSdnB8YbV5lGxItxlKz7xlsb"
OAUTH2_AUTHORIZE_URL = "https://app.rios.org.br/index.php/apps/oauth2/authorize"
OAUTH2_TOKEN_URL = "https://app.rios.org.br/index.php/apps/oauth2/api/v1/token"
OAUTH2_REDIRECT_URI = "https://baobaxia.colaborativas.net"

Instalação do ambiente de desenvolvimento

Requisitos

• git
• git-annex*
• python 3
• pip
• virtualenv

• A versão do git-annex dos repositórios APT pode estar desatualizada. Neste caso podemos utilizar a versão do Neurodebian.

Instruções para instalar o git-annex pelo Neurodebian:

http://neuro.debian.net/

Após configurar o repositório, rodar:

apt update
apt install git-annex-standalone

Preparação do ambiente

Inicialmente, na pasta desejada, clonar o ambiente com:

GIT_SSL_NO_VERIFY=true git clone <url_do_ambiente>.git

Antes de entrar na pasta baixada, preparar o ambiente virtual:

virtualenv venv-bbx
. ./venv-bbx/bin/activate

Instalação das dependências

Na pasta do projeto, ativar o ambiente virtual e rodar o pip:

cd baobaxia-mucua
pip install -r requirements/dev.txt

Configuração inicial da Mucua

A mucua deve estar em execução. Em um novo terminal, na pasta do projeto, ativar e entrar no console do Python:

cd baobaxia-mucua
. ./bin/activate
python3

Dentro do console do Python, importar e rodar o instalador interativo:

from baobaxia.install import install_interactive
install_interactive()

Preencher as informações necessárias para o instalador:

• Caminho do diretório de dados: pasta onde ficarão os repositórios (ex.: /home/user/.bbx/data)
• Nome do balaio: nome do repositório compartilhado entre as mucuas (ex.: Rede Mocambos)
• Nome da mucua: nome da instância local da Baobáxia, usar algo significativo para a comunidade ou coletivo que vai alimentar a mucua (ex.: Abdias)
• Nome de usuário: username da/o mocambola padrão (ex.: exu)
• E-mail: e-mail da/o mocambola padrão (ex.: exu@mocambos.net)
• Senha: senha da/o mocambola padrão

Configurações de chave primária (ver detalhes abaixo)

• Tamanho da chave aleatória (smid): tamanho, em caracteres, do identificador gerado aleatoriamente para os saberes (ex.: 7)
• Tamanho do nome na chave primária: número de caracteres do nome do Saber que será usado para compor o slug (ex.: 20)
• Tamanho da chave aleatória na chave primária: número de caracteres do identificador aleatório que será utilizado para compor o slug (ex.: 7)
• Separador da chave primária: caracter que será usado para separar o nome do identificador aleatório quando montar o slug (ex.: -)

Execução da mucua

Caso o ambiente virtual não esteja ativo:

cd baobaxia-mucua
. ./bin/activate

Executar o Uvicorn (em primeiro plano, terminal fica dedicado e logs são escritos no stdout):

uvicorn baobaxia.acervo:api --host 0.0.0.0 --port 8000 --reload

A porta pode ser alterada conforme sua preferência. A flag --reload instrui o Uvicorn a monitorar os arquivos e recarregar a mucua quando houver alterações.

Chave primária: idenficador aleatório (smid) e slug

O identificador aleatório (small id ou smid) é gerado automaticamente pela plataforma e serve como chave primária para os saberes. O número de caracteres dessa chave deve ser suficiente para evitar colisão.

O slug é o identificador composto, usado para que o caminho do Saber seja mais intuitivo para quem está acessando o sistema. Por exemplo, o balaio chamado Rede Mocambos que receber um identificador aleatório A1B2C3D teria um slug parecido com rede-mocambos-A1B2C3D.

Instalação e execução com Docker

TODO: Parametrizar variáveis

Por simplicidade algumas variáveis serão definidas seguindo valores padrões:

# ! Não executar, só para registro. Essas cosntantes estão definidas em `baobaxia/constants.py`

DEFAULT_USER_HOME = "/home/exu"
DEFAULT_GALAXIAS_PATH = "/home/exu/bbx/galaxias"
DEFAULT_GALAXIA_NAME = "Galáxia base"
DEFAULT_MUCUA_NAME = "Mucua local"
DEFAULT_MOCAMBOLA = "exu"
DEFAULT_MOCAMBOLA_NAME = "Exu"
DEFAULT_MOCAMBOLA_EMAIL = "exu@mocambos.net"
DEFAULT_MOCAMBOLA_PASSWORD = "livre"
DEFAULT_SMID_LEN = 32
DEFAULT_SLUG_NAME_LEN = 31
DEFAULT_SLUG_SMID_LEN = 4
DEFAULT_TTL = 3

Construção das imagens base

Para executar a construção do Baobáxia devemos construir as imagens base primeiro:

bash scripts/build-base-images.sh

Este script irá construir duas imagens: poetry:latest e bbx-base:latest, as tags podem ser alteradas parametrizando o script scripts/build-base-images.sh.

Instalação do Baobáxia

Criar a imagem com dados pré-definidos:

docker build -t bbx .

Realizar a instalação inicial do Baobáxia na imagem:

ATENĆÃO: Passo necessário apenas na primeira execução! TODO: Verificar idepotência. O que ocorre com duas execuções sequênciais?

CONTAINER_NAME="bbx"
VOLUME_NAME="bbx_volume"
CONTAINER_VOLUME_TARGET="/home/exu"

bash scripts/init-bbx.sh ${CONTAINER_NAME} ${VOLUME_NAME} ${CONTAINER_VOLUME_TARGET}

Execução com Docker

Utilizando as mesmas variáveis de ambiente do último passo:

docker run -p 8000:8000 --mount type=volume,src=${VOLUME_NAME},dst=${CONTAINER_VOLUME_TARGET} --restart always -d --name ${CONTAINER_NAME} bbx

Pronto, agora você já tem a API de Baobáxia rodando localmente e possui uma mucua criada. Você poderá acessar a API pelo enderećo localhost:8000 e a documentaćão em localhost:8000/docs

Resolućão de problemas

Failed to bind port

docker: Error response from daemon: driver failed programming external connectivity on endpoint bbx (...): failed to bind port 0.0.0.0:8000/tcp: Error starting userland proxy: listen tcp4 0.0.0.0:8000: bind: address already in use.

Ao rodar o Docker você está indicando um mapeamento da porta 8000 da sua máquina, na porta 8000 do container. Se a sua máquina tiver outra aplicaćão rodando na porta 8000 será necessário trocar o mapeamento, por exemplo para a porta 8001:

docker run -p 8001:8000 --mount type=volume,src=${VOLUME_NAME},dst=${CONTAINER_VOLUME_TARGET} --restart always -d --name ${CONTAINER_NAME} bbx

Container name already in use

docker: Error response from daemon: Conflict. The container name "/bbx" is already in use by container "...". You have to remove (or rename) that container to be able to reuse that name.

Este erro pode ocorrer se você já criou um container com o mesmo nome. Você pode tanto remover o container anterior, caso o nome escolhido seja bbx: docker rm bbx. Como renomear a tentativa de subida atual, por exemplo para bbx-1: CONTAINER_NAME="bbx-1" docker run -p 8000:8000 --mount type=volume,src=${VOLUME_NAME},dst=${CONTAINER_VOLUME_TARGET} --restart always -d --name ${CONTAINER_NAME} bbx

Limpeza completa do ambiente Docker

Executar em sequência os seguinte passos:

1. Parar todos os containers ativos: docker stop `docker ps -qa`
2. Remover todos os containers: docker rm `docker ps -qa`
3. Limpeza completa: docker system prune -f --all