Guia de instalação e operação

Este guia destina-se às equipas de TI que instalam a Amanova nos seus próprios servidores, na sua própria conta de nuvem ou numa rede isolada (air-gapped). O serviço alojado operado pela SMH Global Services não precisa de nada disto.

1. O que é instalado

Componente	O que faz
Aplicação	A aplicação web da Amanova, o espaço de trabalho das equipas, o portal do cliente e as APIs
Servidor web	Disponibiliza a aplicação e os ficheiros estáticos dentro da instalação
Processos em segundo plano e agendador	Verificações de documentos, análise de extratos, pontuações de alerta precoce, relatórios e lembretes
Serviço em tempo real	Atualizações em direto no navegador
MariaDB 11.8	A base de dados, numa rede interna sem acesso a partir do exterior
Redis	Cache e filas de tarefas
Caddy	HTTPS à frente de tudo, com certificados automáticos ou os seus próprios
`amanova.sh`	O script de operações: instalação, cópia de segurança, restauro, atualização, subscrição, relatório de utilização

Tudo é executado em contentores com Docker Compose. Os dados ficam em volumes Docker; as cópias de segurança são gravadas em /opt/amanova/backups.

2. Requisitos

	Piloto	Produção
CPU	4 vCPU	8 vCPU
Memória	8 GB	16 GB
Disco	SSD de 60 GB	SSD de 200 GB, mais armazenamento para cópias de segurança
Sistema operativo	Ubuntu 22.04 ou 24.04, RHEL 9 ou compatível	Igual
Software	Docker Engine 24 ou posterior, com o plugin Compose	Igual

Também precisa de:

um nome de anfitrião que os utilizadores vão escrever, por exemplo lending.bank.local, apontado para o servidor;
as portas 80 e 443 abertas aos seus utilizadores (a porta 80 apenas redireciona para a 443);
para certificados automáticos na Internet, o nome de anfitrião tem de ser público; numa rede interna, utilize o seu próprio certificado (secção 6).

3. Instalação padrão (servidor com acesso à Internet)

sudo tar -xzf amanova-2.1.0-onprem.tar.gz -C /opt
sudo mv /opt/amanova-2.1.0-onprem /opt/amanova
cd /opt/amanova
sudo ./amanova.sh install

O script pede:

o endereço que os utilizadores vão escrever (nome de anfitrião);
o nome do credor;
o país principal (PK, BD, SA, AE, NG, KE, EG, GH, SN ou MZ);
o endereço de e-mail do primeiro administrador.

Em seguida, constrói ou carrega a imagem da aplicação, inicia os serviços, cria o site com palavras-passe aleatórias para a base de dados e para o administrador (guardadas em /opt/amanova/.env, que só o root pode ler), e mostra o endereço e a primeira palavra-passe do administrador. A primeira construção demora 15 a 25 minutos.

4. Instalação offline (rede isolada)

Peça à SMH Global o arquivo de imagens da sua versão, amanova-2.1.0-images.tar.gz. Copie os dois ficheiros para o servidor e, depois:

sudo tar -xzf amanova-2.1.0-onprem.tar.gz -C /opt
sudo mv /opt/amanova-2.1.0-onprem /opt/amanova
cd /opt/amanova
sudo ./amanova.sh load-images /path/to/amanova-2.1.0-images.tar.gz
sudo ./amanova.sh install --offline

Nada é descarregado. O motor de IA integrado funciona sem ligação; para utilizar modelos de IA, execute um servidor de modelos nas instalações (secção 10).

Inicie sessão em https://<your host>/login como administrador e altere a palavra-passe.
Amanova Settings: nome do credor, marca, país principal, idiomas, telefone e e-mail de suporte.
Country Pack: confirme com a sua equipa de conformidade as regras de identificação, de telemóvel, da central de crédito e de concessão de crédito.
Loan Product: crie os seus produtos, limites, taxas e documentos obrigatórios; assinale Show on portal para os produtos online.
Users: adicione membros da equipa com as funções Loan Officer, Loan Underwriter, Loan Manager, Compliance Officer ou Auditor.
Amanova Compliance Settings: ative a autenticação de dois fatores para as equipas e defina os pontos de controlo de triagem, KYC e aprovação.
Instale o seu ficheiro de subscrição (secção 9).

6. Certificado TLS

Nome de anfitrião público: o Caddy obtém e renova um certificado automaticamente.
Nome de anfitrião interno: coloque o seu certificado e a chave em /opt/amanova/certs/ como site.crt e site.key e, depois, execute sudo ./amanova.sh cert. Utilize a cadeia completa em site.crt.

7. Cópia de segurança e restauro

sudo ./amanova.sh backup              # database and files, with a SHA-256 checksum
sudo ./amanova.sh backups             # list backups
sudo ./amanova.sh restore <folder>    # verifies the checksum, then restores

É feita uma cópia de segurança todas as noites às 02:00 e são mantidas as 14 mais recentes (BACKUP_KEEP em .env). Copie /opt/amanova/backups para um armazenamento separado; a chave de cifragem da base de dados está em .env e tem de ser copiada à parte e guardada em segurança.

8. Atualizações

sudo tar -xzf amanova-2.2.0-onprem.tar.gz -C /tmp
sudo /tmp/amanova-2.2.0-onprem/amanova.sh upgrade /opt/amanova

A atualização faz primeiro uma cópia de segurança, substitui os ficheiros da aplicação (o seu .env, os certificados, a subscrição e as cópias de segurança são mantidos), reconstrói ou carrega a nova imagem, migra a base de dados e reinicia. Os sites em rede isolada carregam primeiro o novo arquivo de imagens. As instalações clonadas a partir do repositório da SMH Global podem executar sudo ./amanova.sh update para obter e aplicar a versão mais recente.

9. Ficheiro de subscrição e relatório de utilização

O ficheiro de subscrição é assinado pela SMH Global e verificado offline com a chave pública incluída no produto; nada comunica com o fornecedor. Regista o licenciado, os utilizadores internos, o escalão de carteira, os módulos, os países, o prazo e a data de fim do suporte.

sudo ./amanova.sh subscription /path/to/subscription.json   # install or replace
sudo ./amanova.sh subscription                              # show status
sudo ./amanova.sh usage-report                              # writes usage-report-<date>.json with a checksum

Os administradores veem também a subscrição, a utilização e a expiração em Amanova Subscription na aplicação. Quando a subscrição ou o período de suporte terminam, ou a utilização ultrapassa o montante subscrito, os administradores veem um aviso; a concessão de crédito, a gestão e a cobrança continuam a funcionar. Envie à SMH Global um relatório de utilização todos os trimestres, ou quando lhe for pedido.

10. Opções de IA

Em Amanova Settings → Market & AI:

Fornecedor	Para onde vão os dados
Integrado	Para lado nenhum: regras e estatísticas dentro da sua instalação
Nas instalações	O seu próprio servidor de modelos com uma API compatível com OpenAI (por exemplo, vLLM ou Ollama), definido pelo respetivo URL
Anthropic Claude ou nuvem compatível com OpenAI	O fornecedor que aprovar, com a sua chave de API, guardada cifrada

Cada resultado da IA fica registado com os dados de entrada e a pessoa que o aceitou ou rejeitou. Nada é decidido apenas pela IA.

11. Notas de segurança para a análise de segurança da informação

Os contentores executam a aplicação como utilizador sem privilégios de root; a base de dados e o Redis não têm portas publicadas.
Apenas HTTPS, TLS 1.2 e 1.3; o HTTP é redirecionado para HTTPS.
As palavras-passe são guardadas com hash; segredos como as chaves de API são cifrados com a chave do site em .env.
A autenticação de dois fatores para as equipas, a política de palavras-passe, o bloqueio após tentativas falhadas e a expiração da sessão são configuráveis.
Os documentos dos clientes são ficheiros privados, disponibilizados apenas a utilizadores com sessão iniciada e autorizados a vê-los.
Cada documento mantém um histórico de versões; os resultados da IA ficam registados com o respetivo revisor.

12. Instalação sem contentores

Onde os contentores não são permitidos, a Amanova instala-se com a configuração de produção padrão da plataforma (Python, Node.js, MariaDB, Redis, NGINX e Supervisor) através do bench. Peça à SMH Global o guia systemd/bench para o seu sistema operativo.

13. Resolução de problemas

Sintoma	Verificar
O site não abre	`sudo ./amanova.sh status` e `sudo ./amanova.sh logs web`
Erros de certificado	O nome do anfitrião resolve para o servidor; as portas 80 e 443 estão abertas; ou instale o seu próprio certificado
Verificações em segundo plano lentas	`sudo ./amanova.sh logs worker`; acrescente memória ou CPU
Restauro recusado	A soma de verificação da cópia de segurança não corresponde; copie novamente a cópia de segurança

14. Referência de comandos

Comando	O que faz
`install [--offline]`	Primeira instalação
`status`	Serviços, versão, subscrição e utilização do disco
`start`, `stop`, `restart`	Controlar todos os serviços
`logs [service]`	Acompanhar os registos (`app`, `web`, `worker`, `scheduler`, `db`, `proxy`)
`backup`, `backups`, `restore <folder>`	Cópias de segurança com somas de verificação
`upgrade <folder>` / `update`	Atualizar a partir de um novo pacote, ou obter a versão mais recente do repositório
`load-images <archive>`	Carregar imagens para uma instalação ou atualização offline
`cert`	Utilizar o seu próprio certificado a partir de `certs/`
`subscription [file]`	Instalar ou mostrar a subscrição
`usage-report`	Gerar um relatório de utilização para a SMH Global
`admin-password`	Definir uma nova palavra-passe para o administrador
`version`	Mostrar a versão instalada

Suporte: support@amanova.app · SMH Global Services, Dubai · Carachi · Riade

Guia de instalação e operação.