Instalação: Docker Compose

Instale o KiloCenter com Docker Compose — inicie a stack MIOTY de quatro serviços, incluindo o KC-Web, sem toolchain no host.

Objetivo

Inicie uma stack local funcional usando Docker Compose. A stack completa — incluindo o KC-Web — é executada inteiramente em contentores. Não é necessário o toolchain Go do host nem o runtime Bun.

Passo 1: Configurar o Ambiente

De kilocenter-modules/:

cp .env.example .env

Editar .env se quiser alterar as credenciais da base de dados ou o nível de registo. As predefinições funcionam para uma avaliação local.

Passo 2: Gerar Certificados TLS

O KC-Core requer certificados TLS para BSSCI e SCACI. Gere-os usando o certgen serviço incorporado na imagem do KC-Core:

docker compose run --rm certgen

Propriedade dos arquivos (Linux): Se os arquivos gerados pertencerem ao root, execute novamente com UID=$(id -u) GID=$(id -g) como prefixo.

Isto cria quatro ficheiros em KC-Core/certificates/:

Ficheiro	Finalidade
ca.crt	Certificado da CA (distribuir às estações de base)
ca.key	Chave privada da CA (mantenha em segurança, usada para assinar certificados de cliente)
server.crt	Certificado do servidor (usado pelos listeners TLS BSSCI/SCACI do KC-Core)
server.key	Chave privada do servidor

Para um FQDN de produção, passe -server:

docker compose run --rm certgen -dir /app/certificates -days 365 -server bssci.example.com

Importante: O KC-Core não conseguirá iniciar sem estes certificados. Consulte a página de Segurança para a referência completa dos flags do certgen, renovação de certificados e geração de certificados de cliente.

Passo 3: Iniciar Todos os Serviços

docker compose up --build -d

Isto compila e inicia todos os sete serviços em tempo de execução. Inícios subsequentes após uma recompilação usam camadas em cache sempre que possível.

Passo 4: Validar o Arranque

# Verifique se todos os serviços estão a funcionar
docker compose ps

# Saúde do KC-Core
curl -s http://localhost:8086/health

# Saúde do KC-Gateway
curl -s http://localhost:8087/health

# Verifique o proxy gRPC-web do nginx (200/401/403 = OK; 502/404 = proxy avariado)
curl -s -o /dev/null -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/grpc-web+proto" \
  -H "X-Grpc-Web: 1" \
  --data-binary $'\x00\x00\x00\x00\x00' \
  http://localhost/kilocenter.api.v1.KiloCenterService/GetSystemStatus

Depois abra o KC-Web no seu navegador:

• http://localhost/

Nota: A integração MQTT está desativada por predefinição. O broker Mosquitto é executado em Docker, mas o KC-Core não se liga a ele até ativar o MQTT em config/config.docker.yaml. Consulte os Primeiros Passos com MQTT quando estiver pronto para configurar o MQTT.

Parar Todos os Serviços

docker compose down

Para remover também os volumes de dados persistentes:

docker compose down -v

---

Modo de Desenvolvimento a partir do Código-Fonte

Para colaboradores que querem executar o KC-Core, KC-Gateway e KC-Web a partir do código-fonte:

Passo 1: Iniciar os Contentores de Infraestrutura

docker compose up -d postgres redis mosquitto

Isto inicia o PostgreSQL (mapeado para a porta anfitriã 5433), Redis (6379) e Mosquitto (1883).

Passo 2: Gerar Certificados TLS

Igual ao anterior — use o certgen serviço compose:

docker compose run --rm certgen

Passo 3: Instalar as Dependências do KC-Web

De kilocenter-modules/KC-Web/:

bun install

Passo 4: Iniciar Todos os Serviços a partir do Código-Fonte

De kilocenter-modules/:

./start-dev.sh

Isto compila e inicia o KC-Core, o KC-Gateway e o KC-Web. Os registos são escritos em logs/runtime/. O KC-Web está disponível em http://localhost:5173.

Parar os Serviços do Código-Fonte

./stop-all-services.sh

# Parar os contentores de infraestrutura
docker compose stop postgres redis mosquitto