Executar as imagens do Archestack

O Archestack são duas imagens de contentor e uma base de dados PostgreSQL. Todas as formas de o correr, de um portátil a um cluster Kubernetes, arrancam as mesmas duas imagens com definições diferentes. Esta página diz o que são, o que qualquer instalação lhes tem de dar e que forma de as correr serve para onde. Todas as definições que as imagens aceitam estão em Definições das imagens.

As imagens

Cada release leva como tag a sua versão, como 1.0.42, e a mais recente é também latest. Em produção, corra um número de versão, para saber o que corre e poder levar essa mesma versão do teste à produção. A API e a imagem web de uma release andam juntas.

O que qualquer instalação lhes dá

1. PostgreSQL 16, com um utilizador que possa criar bases de dados. A API cria as suas próprias bases de dados no primeiro arranque e depois um par por cada espaço de trabalho, por isso não há nada a preparar. Dê ao PostgreSQL 1 GB de memória partilhada (--shm-size 1g no Docker): as suas estatísticas crescem com cada base de dados, e o valor predefinido esgota-se por volta dos mil espaços de trabalho.
2. Duas pastas que sobrevivem a um reinício, /files para os uploads e /backups para os backups. Sem elas, os uploads desaparecem na próxima atualização.
3. Um caminho até cada imagem. O browser carrega a imagem web e chama a API em /api, com as atualizações em tempo real por um WebSocket em /hubs. Ambas podem partilhar um só endereço, como fazem os kits iniciais, ou a API tem um endereço próprio:

   One address (the kits do this)          Two addresses
   
   https://apps.example.com                https://editor.example.com  ->  omnicore-web
     /api/...   ->  omnicore-api :8080     https://api.example.com     ->  omnicore-api
     /hubs/...  ->  omnicore-api :8080
     /...       ->  omnicore-web :80       VITE_API_URL=https://api.example.com
   
   VITE_API_URL empty

   Sob um caminho de um hostname, como https://apps.example.com/archestack/, ambas as imagens recebem o caminho (BASE_PATH e Http__PathBase).
4. Um primeiro admin. Defina Identity__InitialAdminEmail e Identity__InitialAdminPassword, ou abra o builder logo após o primeiro arranque e crie lá o admin. Enquanto ninguém o fizer, quem chegar primeiro ao builder torna-se admin, por isso não deixe uma instalação nova aberta na internet.
5. Tempo para arrancar. A API só responde a /health com {"status":"ok"} depois de todas as bases de dados estarem migradas. Um primeiro arranque demora um ou dois minutos, e mais com muitos espaços de trabalho, por isso verifique a prontidão em /health e dê ao arranque tempo suficiente.

As formas de as correr

Seja qual for a escolha, as suas aplicações chegam lá da mesma forma: a partir do repositório, através de um pipeline.

Experimentar com docker run

Três contentores numa rede Docker: o PostgreSQL, a API na porta 8080 e o builder na porta 8081. Escolha uma palavra-passe sua em vez de change-me.

# Archestack on this machine with plain docker run: the builder on http://localhost:8081
docker network create archestack
docker volume create archestack-postgres

docker run -d --name archestack-postgres --network archestack --shm-size 1g \
  -e POSTGRES_USER=archestack -e POSTGRES_PASSWORD=change-me -e POSTGRES_DB=postgres \
  -v archestack-postgres:/var/lib/postgresql/data postgres:16

docker run -d --name archestack-api --network archestack -p 8080:8080 \
  -e ASPNETCORE_URLS=http://+:8080 \
  -e "ConnectionStrings__DefaultConnection=Host=archestack-postgres;Database=omnicore-db;Username=archestack;Password=change-me" \
  -e "ConnectionStrings__Core=Host=archestack-postgres;Database=omnicore-core;Username=archestack;Password=change-me" \
  -e "ConnectionStrings__Identity=Host=archestack-postgres;Database=omnicore-identity;Username=archestack;Password=change-me" \
  -e ConnectionStrings__Keycloak= \
  -e Database__CreateMissing=true \
  -e Identity__Provider=Builtin -e Identity__AppBaseUrl=http://localhost:8081 \
  -e Files__Directory=/files -e Backup__Directory=/backups \
  -v archestack-files:/files -v archestack-backups:/backups \
  nickpeelman/omnicore-api:latest

docker run -d --name archestack-web --network archestack -p 8081:80 \
  -e VITE_API_URL=http://localhost:8080 -e VITE_UI_MODE=dashboard \
  -e API_INTERNAL_URL=http://archestack-api:8080 \
  nickpeelman/omnicore-web:latest

Abra http://localhost:8081 quando http://localhost:8080/health responder, e crie o primeiro admin. O builder e a aplicação publicada (/app) estão ambos nessa porta, e a API na 8080 responde diretamente ao browser. Para remover tudo outra vez:

docker rm -f archestack-web archestack-api archestack-postgres
docker network rm archestack
# Everything you made is in the volumes; this deletes it:
docker volume rm archestack-postgres archestack-files archestack-backups

Isto serve para experimentar. Um servidor precisa de reinícios, atualizações, certificados e backups levados para fora da máquina, que é o que Alojamento com Docker configura.

Outras plataformas de contentores

O Azure Container Apps, o Amazon ECS, o Google Cloud Run e plataformas semelhantes correm as mesmas imagens. Verifique estes pontos antes de escolher uma:

• A base de dados. Use o PostgreSQL 16 gerido da plataforma (Azure Database for PostgreSQL, Amazon RDS, Cloud SQL), com um utilizador que possa criar bases de dados. Não corra o próprio PostgreSQL numa partilha de rede.
• Um volume para /files e /backups, como Azure Files, Amazon EFS ou Filestore. Com mais de uma instância da API, todas as instâncias montam o mesmo.
• Pelo menos uma instância da API sempre a correr. Os eventos agendados, a caixa de saída do email e os backups correm dentro da API, por isso uma plataforma que escala até zero para-os. Defina o mínimo como uma instância e, no Cloud Run, mantenha o CPU atribuído fora dos pedidos.
• WebSockets para /hubs, para as atualizações em tempo real. Uma ligação que a plataforma corta é reaberta, mas um timeout de inatividade muito curto faz as atualizações chegarem tarde.
• Pedidos grandes. As importações de pacotes e os uploads de ficheiros podem ser grandes: permita bodies de pedido de pelo menos 100 MB e pedidos que demorem alguns minutos.
• Mais de uma instância da API funciona sem sticky sessions: partilham o seu estado através do PostgreSQL. Para isso, cada uma precisa de uma ligação direta a ele, por isso com um connection pooler como o PgBouncer pelo meio, defina ConnectionStrings__Cluster para o próprio PostgreSQL.

Para onde seguir a partir daqui

Definições das imagens lista todas as definições das duas imagens. Capacidade e dimensionamento diz quanto aguenta uma instalação, e Espaços de trabalho e alojamento como os espaços de trabalho a partilham.