Atualização das instruções de instalação

README.md

@@ -74,91 +74,142 @@ Processo: 18/23094-4
 
 ## Características da versão
 
-# Instalar
+# Instalação
 
-## Instalação com docker
+## Instalação do ambiente de desenvolvimento
 
-Criar a imagem com dados padrões da Casa de Cultura Tainã:
+### Requisitos
 
-```
-sudo docker build -t bbx-fastapi .
-```
+- git
+- git-annex*
+- python 3
+- pip
+- virtualenv
 
-Criar a imagem com dados personalizados:
+* 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:
 
 ```
-sudo docker build -t bbx-fastapi \
-    --build-arg BALAIO='Nosso Balaio' \
-    --build-arg EMAIL='a-gente@email.net' \
-    --build-arg MOCAMBO='Comunidade' \
-    --build-arg MOCAMBOLA='mocambola' \
-    --build-arg MUCUA='Itinerante' \
-    --build-arg SENHA='tem que trocar' .
+apt update
+apt install git-annex-standalone
 ```
 
-e iniciar com
+### Preparação do ambiente
+
+Inicialmente, na pasta desejada, clonar o ambiente com:
 
 ```
-sudo docker run --name xango1 -p 80:80 bbx-fastapi
+git clone <url_do_ambiente>.git
 ```
 
-Pronto, agora você já tem a API de Baobáxia rodando e possui uma mucua criada.
+Antes de entrar na pasta baixada, preparar o ambiente virtual:
 
----
+```
+virtualenv baobaxia-mucua
+```
 
-## Instalação com virtualenv e pip
+### Instalação das dependências
 
-Instalar os pacotes de sistema necessarios, no caso de debian/ubuntu:
+Na pasta do projeto, ativar o ambiente virtual e rodar o `pip`:
 
 ```
-apt install git git-annex virtualenv 
+cd baobaxia-mucua
+. ./bin/activate
+pip install -r requirements/dev.txt
 ```
 
-As vezes a versão do git-annex de sistema não é tão recente então precisa 
-adicionar um repositório seguindo as informações disponíveis aqui:
-
-http://neuro.debian.net/
+### Execução da mucua
 
-e novamente rodar:
+Caso o ambiente virtual não esteja ativo:
 
 ```
-apt update
-apt install git-annex-standalone
+cd baobaxia-mucua
+. ./bin/activate
 ```
 
-Criar um virtualenv com 
+Executar o Uvicorn (em primeiro plano, terminal fica dedicado e logs são escritos no stdout):
+
 ```
-virtualenv nomevirtualenv
+uvicorn baobaxia.acervo:api --host 0.0.0.0 --port 8000 --reload
 ```
 
-Ativar o ambiente com
+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.
+
+# 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:
+
 ```
-. /caminho/para/nomevirtualenv/bin/activate
+cd baobaxia-mucua
+. ./bin/activate
+python3
+
 ```
 
-Para instalar digite:
+Dentro do console do Python, importar e rodar o instalador interativo:
 
+```python
+from baobaxia.install import install_interactive
+install_interactive()
 ```
-pip install baobaxia
-```
 
-# Criar uma mucua e um balaio
+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.: `-`)
+
+
+### Chave primária: idenficador aleatório (smid) e slug
 
-Depois de instalar o software do Baobáxia, precisa criar uma mucua e um balaio
-usando o comando *criar_mucua*, por exemplo:
+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 com docker
+
+**A instalação via docker está desatualizada, para desenvolvimento, usar "Instalação do ambiente de desenvolvimento".**
+
+Criar a imagem com dados padrões da Casa de Cultura Tainã:
 
 ```
-criar_mucua --path='/data/bbx/balaios' --balaio='Rede Mocambos Acervo' \
---mucua='Abdias Nascimento' --mocambo='Casa de Cultura Tainã' \
---mocambola='mocambola' --email='mocambola@mocambos.net' --password='livre' \
---smid_len=13 --slug_name_len=21 --slug_smid_len=5 --slug_sep "_"
+sudo docker build -t bbx-fastapi .
 ```
 
-Pode ver as opções chamando com opção --help.
+Criar a imagem com dados personalizados:
+
+```
+sudo docker build -t bbx-fastapi \
+    --build-arg BALAIO='Nosso Balaio' \
+    --build-arg EMAIL='a-gente@email.net' \
+    --build-arg MOCAMBO='Comunidade' \
+    --build-arg MOCAMBOLA='mocambola' \
+    --build-arg MUCUA='Itinerante' \
+    --build-arg SENHA='tem que trocar' .
+```
 
-Em seguida para rodar a API da aplicação *acervo*:
+e iniciar com
 
 ```
-uvicorn baobaxia.acervo:api --host 0.0.0.0 --port 80
+sudo docker run --name xango1 -p 80:80 bbx-fastapi
 ```
 
+Pronto, agora você já tem a API de Baobáxia rodando e possui uma mucua criada.
+
+---
+