runv-server

server tooling for runv.club
Log | Files | Refs | README

00-overview.md (2919B)

      1 # Visão geral
      2 
      3 [← Índice](README.md)
      4 
      5 ## O que é o runv-server
      6 
      7 Repositório de **scripts (principalmente Python 3, biblioteca padrão)**, conteúdo estático web e documentação para operar um servidor **pubnix** estilo tilde (**runv.club**) em **Debian**. Não é uma aplicação web monolítica (sem `package.json` na raiz do produto).
      8 
      9 ## Âmbito do repositório
     10 
     11 - **Infraestrutura:** bootstrap (`starthere.py`), quotas ext4, Apache, UFW, ferramentas globais (`tools.py`).
     12 - **Site público:** landing estática em `site/public/`, geração de Apache (`genlanding.py`), dados públicos de membros (`build_directory.py`).
     13 - **Email transacional:** Mailgun HTTP por defeito; modo legado SMTP/msmtp (`email/`).
     14 - **Pedidos de conta:** fluxo SSH ao utilizador `entre` (`terminal/`) — **fila em JSON**, sem criar contas Unix automaticamente.
     15 - **Provisionamento canónico:** `scripts/admin/create_runv_user.py` cria utilizador Unix, home, jail, quota, metadados.
     16 
     17 ## Resumo arquitetural
     18 
     19 | Componente | Responsabilidade |
     20 |------------|------------------|
     21 | `terminal/` | Recolher, validar, enfileirar pedidos; **não** faz `adduser` de membros. |
     22 | `create_runv_user.py` | **Única** fonte canónica do fluxo de criação de conta membro (ordem documentada na docstring). |
     23 | `users.json` | Metadados dos membros no servidor (`/var/lib/runv/users.json`). |
     24 | Fila `entre-queue/` | Pedidos pendentes de revisão humana antes do provisionamento. |
     25 | `build_directory.py` | Lê `users.json` → gera `members.json` **filtrado** para o site. |
     26 
     27 Diagrama: [diagrams/architecture.mmd](diagrams/architecture.mmd).
     28 
     29 ## Ciclo de vida de um novo membro
     30 
     31 1. Visitante liga `ssh entre@…` e preenche o fluxo guiado.
     32 2. Gera-se um ficheiro JSON na fila (`/var/lib/runv/entre-queue/`).
     33 3. **Admin** revê o pedido e executa `create_runv_user.py` (root).
     34 4. Actualiza-se `users.json`; opcionalmente regera-se `DocumentRoot/data/members.json` (constelação na landing).
     35 5. O membro aparece na lista pública **só** com campos não sensíveis.
     36 
     37 Diagrama: [diagrams/member-flow.mmd](diagrams/member-flow.mmd).
     38 
     39 ## Fronteira dados públicos / privados
     40 
     41 - **Público (`members.json`):** apenas o que `build_directory.py` escreve: `username`, `since`, `path`, opcionalmente `homepage_mtime` (com `--homes-root`). Ver [07-public-members-directory.md](07-public-members-directory.md).
     42 - **Privado:** email, fingerprint de chave, quotas detalhadas, campos internos de `users.json` **não** são copiados para o JSON público (garantido no código de `build_directory.py`).
     43 
     44 ## Fontes de verdade
     45 
     46 1. **Código** dos scripts referidos neste índice.
     47 2. O **`INSTALL.md` da raiz** e a documentação `.md` nos módulos foram **substituídos** por esta árvore `docs/` (conteúdo absorvido e harmonizado; ver `DOCS_REBUILD_CHANGELOG.md`).
     48 3. Docstrings de `starthere.py`, `create_runv_user.py`, `setup_entre.py`, `genlanding.py`, etc.