Skip to main content

Containers

This document was generated using AI assistance

Content may include inaccuracies, outdated information, or technical errors. Users are advised to cross-check critical information before implementation.

Architeezy runs as a set of containers described by a single docker-compose.yml. The services address each other by container name on the compose network.

All published ports are bound to 127.0.0.1, so nothing is reachable from outside the host until you put a reverse proxy in front of it. Each port is set by a variable in the .env file, so moving a service to a free port takes no edit to the compose file.

Services​

frontend​

Container architeezy-frontend. Nginx serving the user interface - static HTML, JavaScript and CSS - and proxying the application requests to the API gateway: /api/, /subscriptions, /mcp, /login, /logout, /account, /authenticate, /oauth2/ and /.well-known/.

This is the only service users need to reach. It listens on port 8080 inside the container and is published on FRONTEND_PORT (8080 by default). Its health endpoint is /health.

api-gateway​

Container architeezy-api-gateway. Handles authentication: it runs the OAuth 2.0 authorization code flow against Keycloak, keeps the user session in Redis, and routes /api/**, /subscriptions and /mcp/** to the backend. It also sends mail through the SMTP server, when one is configured.

Listens on port 8081 inside the container and is not published to the host. Its health endpoint is /actuator/health.

backend​

Container architeezy-backend. The core application: projects, models, representations, validation, expressions and the AI assistant. It stores everything in the application database and verifies incoming tokens against the Keycloak key set.

Listens on port 8082 inside the container and is not published to the host. Its health endpoint is /actuator/health.

db​

Container architeezy-db. PostgreSQL 18 holding the architeezy database - projects, models, representations and uploaded images. The data is kept in the architeezy-db-data volume. Published on DATABASE_PORT (5441 by default) for local administration.

redis​

Container architeezy-redis. Stores user sessions, so users stay signed in across restarts of the API gateway. Runs with append-only persistence into the architeezy-redis-data volume and requires the password from REDIS_PASSWORD. Published on REDIS_PORT (6382 by default).

keycloak​

Container architeezy-keycloak. The identity and access management system. The image bundles the architeezy realm and imports it on first start. Published on KEYCLOAK_PORT (8181 by default); users reach it during sign-in, so it needs a public address of its own.

keycloak-db​

Container architeezy-keycloak-db. PostgreSQL 18 holding the keycloak database - user accounts, credentials and realm configuration. The data is kept in the architeezy-keycloak-db-data volume. Published on KEYCLOAK_DATABASE_PORT (5444 by default).

Startup order​

Compose starts the services in dependency order and waits for health checks along the way:

  1. db, keycloak-db and redis come up first.
  2. keycloak waits for keycloak-db.
  3. backend waits for db and keycloak.
  4. api-gateway waits for redis, backend and keycloak.
  5. frontend waits for api-gateway.

backend, api-gateway and keycloak allow 60 seconds before their health checks start counting, so the first docker compose up on a cold machine takes a couple of minutes before the interface answers.