Installation Guide

1. Prerequisites

Archinsight is designed as a microservice-based system and is distributed as a set of Docker images. It can be deployed in any Docker-compatible environment, including local development setups, cloud platforms, and container orchestration systems.

The official Docker Hub repository provides ready-to-use images, for simple deployment.

2. Infrastructure Setup

At a minimum, the following components must be available:

  • PostgreSQL 15.4 or higher – Required for the identity and repository services.
  • Reverse Proxy – A proxy such as Traefik, Nginx, or Envoy is needed for routing and secure service access.

2.1 Database Setup

Before deploying Archinsight, ensure that:

  • Separate databases are created for the identity and repository services.
  • Dedicated database users are assigned to each service.
  • Users have sufficient permissions to perform DDL operations using Flyway migrations.

The database schema will be automatically initialized when the services start, applying all required migrations. No manual schema setup is needed.

2.2 Reverse Proxy Routes

The routing rules should be configured as follows:

Path Prefix Target Service Purpose
/oauth identity Routes OAuth provider callbacks to the identity service.
/auth/ identity Handles authentication-related requests (note the trailing slash).
/ editor-ui Default route, forwarding all other requests to the editor UI.

3. Service Deployment

Archinsight can be deployed using Docker Compose, which simplifies service management by defining configurations in a single file. Following examples represent basic configuration and can be modified to meet specific requirements.

3.1 Renderer

Docker Compose

  renderer:
    image: "lonelylockley/archinsight:renderer-latest"
    container_name: renderer
    hostname: renderer
    restart: always
    environment:
      - MICRONAUT_CONFIG_FILES=/etc/application.yml
      - JAVA_TOOL_OPTIONS=-Xms128M -Xmx128M
    networks:
      - archinsight
    volumes:
      - ./application.yml:/etc/application.yml:ro

Configuration Parameters

Parameter Description Default Value
micronaut.server.cors.enabled Enables Cross-Origin Resource Sharing (CORS) true
micronaut.security.authentication Defines authentication mechanism (bearer token) bearer
micronaut.security.enabled Enables security features true
micronaut.security.apiKeys.editor-ui API key for editor-ui authentication (empty) 
micronaut:
  server:
    cors:
      enabled: true
  security:
    authentication: bearer
    enabled: true
    apiKeys:
      editor-ui: '<SECRET_TOKEN>'

Environment Variables

Variable Description Default Value
EDITOR_UI_TOKEN API key for editor-ui authentication (empty)
JAVA_TOOL_OPTIONS JVM parameters (empty)
LOG_LEVEL Logback logging level info
MICRONAUT_CONFIG_FILES Path to service config (empty)
MICRONAUT_SERVER_PORT Port for the service to listen for connections 8080
DEV_MODE Runs service in development mode. Must never be enabled in production! false

3.2 Translator

Docker Compose

  translator:
    image: "lonelylockley/archinsight:translator-latest"
    container_name: translator
    hostname: translator
    restart: always
    environment:
      - MICRONAUT_CONFIG_FILES=/etc/application.yml
      - JAVA_TOOL_OPTIONS=-Xms128M -Xmx128M
    networks:
      - archinsight
    volumes:
      - ./application.yml:/etc/application.yml:ro

Configuration Parameters

Parameter Description Default Value
micronaut.server.cors.enabled Enables Cross-Origin Resource Sharing (CORS) true
micronaut.security.authentication Defines authentication mechanism (bearer token) bearer
micronaut.security.enabled Enables security features true
micronaut.security.apiKeys.editor-ui API key for editor-ui authentication (empty)
micronaut.http.services.repository.url Base URL of the repository service http://repository:8080
archinsight.repositoryAuthToken Authentication token for accessing the repository (empty) 
micronaut:
  server:
    cors:
      enabled: true
  security:
    authentication: bearer
    enabled: true
    apiKeys:
      editor-ui: '<SECRET_TOKEN>'
  http:
    services:
      repository:
        url: 'http://repository:8080'
archinsight:
  repositoryAuthToken: '<SECRET_TOKEN>'

Environment Variables

Variable Description Default Value
EDITOR_UI_TOKEN API key for editor-ui authentication (empty)
REPOSITORY Base URL of the repository service http://repository:8080
REPOSITORY_TOKEN Authentication token for repository access (empty)
JAVA_TOOL_OPTIONS JVM parameters (empty)
LOG_LEVEL Logback logging level info
MICRONAUT_CONFIG_FILES Path to service config (empty)
MICRONAUT_SERVER_PORT Port for the service to listen for connections 8080
DEV_MODE Runs service in development mode. Must never be enabled in production! false

3.3 Identity

Docker Compose

  identity:
    image: "lonelylockley/archinsight:identity-latest"
    container_name: identity
    hostname: identity
    restart: always
    environment:
      - MICRONAUT_CONFIG_FILES=/etc/application.yml
      - JAVA_TOOL_OPTIONS=-Xms128M -Xmx128M
    networks:
      - archinsight
    volumes:
      - ./application.yml:/etc/application.yml:ro
      - ./keys:/home/app/jwk_sets:ro

Configuration Parameters

  • Service Parameters
Parameter Description Default Value
micronaut.server.cors.enabled Enables Cross-Origin Resource Sharing (CORS) true
micronaut.security.authentication Authentication mechanism (idtoken) idtoken
micronaut.security.oauth2.clients.google.client-id Google OAuth Client ID (required)
micronaut.security.oauth2.clients.google.client-secret Google OAuth Client Secret (required)
micronaut.security.oauth2.clients.google.scopes OAuth scopes (openid, profile, email) (set values)
micronaut.security.oauth2.clients.google.openid.issuer OpenID issuer for authentication (Google) https://accounts.google.com
micronaut.security.endpoints.logout.enabled Enables logout endpoint true
micronaut.security.endpoints.logout.get-allowed Allows logout via GET request true
micronaut.security.redirect.prior-to-login Whether to redirect users before login false
micronaut.security.redirect.login-success Redirect URL on successful login ${PUBLIC_HOST}/auth/ok
micronaut.security.redirect.login-failure Redirect URL on login failure ${PUBLIC_HOST}/auth/fail
  • Database Configuration
Parameter Description Default Value
datasources.default.db-type Database type (must be PostgreSQL) POSTGRES
datasources.default.driverClassName JDBC driver class org.postgresql.Driver
datasources.default.url JDBC connection URL jdbc:postgresql://${DATABASE_HOST}:
${DATABASE_PORT}/${DATABASE}
datasources.default.username Database username (required)
datasources.default.password Database password (required)
datasources.default.auto-commit Enables auto-commit transactions true
datasources.default.maximum-pool-size Maximum number of connections in pool 10
datasources.default.minimum-idle Minimum number of idle connections 2
datasources.default.idle-timeout Time (ms) before idle connections are closed 600000
  • Flyway Database Migrations
Parameter Description Default Value
flyway.enabled Enables Flyway for database migrations true
flyway.datasources.default.enabled Enables Flyway on the default datasource false
flyway.datasources.default.locations Migration script locations classpath:migration
  • Service Settings
Parameter Description Default Value
archinsight.devMode Enables development mode false
archinsight.domain Base domain for the service (required)
archinsight.kid Key identifier for authentication (required)
archinsight.apiToken API security token (empty)
archinsight.redirect-uri OAuth callback URL for Google authentication ${PUBLIC_HOST}/oauth/callback/google 
micronaut:
  server:
    cors:
      enabled: true
  security:
    authentication: idtoken
    oauth2:
      clients:
        google:
          client-id: '<Google OAuth Client Id>'
          client-secret: '<Google OAuth Client Secret>'
          scopes:
            - openid
            - profile
            - email
          openid:
            issuer: 'https://accounts.google.com'
    endpoints:
      logout:
        enabled: true
        get-allowed: true
    redirect:
      prior-to-login: false
      login-success: 'http://<PUBLIC_HOST>/auth/ok'
      login-failure: 'http://<PUBLIC_HOST>/auth/fail'
datasources:
  default:
    url: 'jdbc:postgresql://<DB_HOSTNAME>:5432/identity'
    username: '<USER>'
    password: '<PASSWORD>'
flyway:
  enabled: true
  datasources:
    default:
      enabled: false
      locations:
        - classpath:migration
archinsight:
  domain: '<PUBLIC_HOST>'
  kid: '<KEY_ID>'
  apiToken: '<SECRET_TOKEN>'
  redirect-uri: 'http://<PUBLIC_HOST>/oauth/callback/google'

Environment Variables

Variable Description Default Value
OAUTH_CLIENT_ID Google OAuth Client ID (required)
OAUTH_CLIENT_SECRET Google OAuth Client Secret (required)
PUBLIC_HOST Public-facing hostname (required)
DATABASE_HOST PostgreSQL database host (required)
DATABASE_PORT PostgreSQL port (required)
DATABASE PostgreSQL database name (required)
DATABASE_USER PostgreSQL username (required)
DATABASE_PASSWORD PostgreSQL password (required)
DOMAIN Service domain name (required)
KID Key identifier for authentication (required)
SECURITY_TOKEN Security API token (empty)
JAVA_TOOL_OPTIONS JVM parameters (empty)
LOG_LEVEL Logback logging level info
MICRONAUT_CONFIG_FILES Path to service config (empty)
MICRONAUT_SERVER_PORT Port for the service to listen for connections 8080
DEV_MODE Runs service in development mode. Must never be enabled in production! false

JWT Keys Configuration

The Identity service uses its own key pair for working with JWT tokens. In the production environment, you need to generate a new key pair. The service provides a built-in utility, KeyGenerator, for this purpose.

To generate a key pair, run the com.github.lonelylockley.archinsight.KeyGenerator class with two parameters:

  • Key pair identifier
  • Directory to store the generated files

Run command:

java -cp archinsight-identity.jar com.archinsight.identity.KeyGenerator <KEY_ID> ./keys

3.4 Repository

Docker Compose

  repository:
    image: "lonelylockley/archinsight:repository-latest"
    container_name: repository
    hostname: repository
    restart: always
    environment:
      - MICRONAUT_CONFIG_FILES=/etc/application.yml
      - JAVA_TOOL_OPTIONS=-Xms128M -Xmx128M
    networks:
      - archinsight
    volumes:
      - ./application.yml:/etc/application.yml:ro

Configuration Parameters

  • Service Parameters
Parameter Description Default Value
micronaut.server.cors.enabled Enables Cross-Origin Resource Sharing (CORS) true
micronaut.security.authentication Authentication mechanism (bearer token) bearer
micronaut.security.enabled Enables security features true
micronaut.security.apiKeys.editor-ui API key for editor-ui authentication (empty)
micronaut.security.apiKeys.translator API key for translator authentication (empty)
  • Database Configuration
Parameter Description Default Value
datasources.default.db-type Database type (must be PostgreSQL) POSTGRES
datasources.default.driverClassName JDBC driver class org.postgresql.Driver
datasources.default.url JDBC connection URL jdbc:postgresql://${DATABASE_HOST}:
${DATABASE_PORT}/${DATABASE}
datasources.default.username Database username (required)
datasources.default.password Database password (required)
datasources.default.auto-commit Enables auto-commit transactions true
datasources.default.maximum-pool-size Maximum number of connections in pool 10
datasources.default.minimum-idle Minimum number of idle connections 2
datasources.default.idle-timeout Time (ms) before idle connections are closed 600000
  • Flyway Database Migrations
Parameter Description Default Value
flyway.enabled Enables Flyway for database migrations true
flyway.datasources.default.enabled Enables Flyway on the default datasource false
flyway.datasources.default.locations Migration script locations classpath:migration
  • Service Settings
Parameter Description Default Value
archinsight.devMode Enables development mode false
archinsight.playgroundRepositoryId ID of the playground repository 00000000-0000-0000-0000-000000000000 
micronaut:
  server:
    cors:
      enabled: true
  security:
    authentication: bearer
    enabled: true
    apiKeys:
      editor-ui: '<SECRET_TOKEN>'
datasources:
  default:
    url: 'jdbc:postgresql://<DB_HOSTNAME>/repository'
    username: '<USER>'
    password: '<PASSWORD>'
flyway:
  enabled: true
  datasources:
    default:
      enabled: false
      locations:
        - classpath:migration
archinsight:
  playgroundRepositoryId: '<SELECTED_REPOSITORY_UUID>'

Environment Variables

Variable Description Default Value
EDITOR_UI_TOKEN API key for editor-ui authentication (empty)
TRANSLATOR_TOKEN API key for inter-service authentication (empty)
DATABASE_HOST PostgreSQL database host (required)
DATABASE_PORT PostgreSQL port (required)
DATABASE PostgreSQL database name (required)
DATABASE_USER PostgreSQL username (required)
DATABASE_PASSWORD PostgreSQL password (required)
PLAYGROUND_REPOSITORY ID of the default playground repository 00000000-0000-0000-0000-000000000000
JAVA_TOOL_OPTIONS JVM parameters (empty)
LOG_LEVEL Logback logging level info
MICRONAUT_CONFIG_FILES Path to service config (empty)
MICRONAUT_SERVER_PORT Port for the service to listen for connections 8080
DEV_MODE Runs service in development mode. Must never be enabled in production! false

3.5 Editor UI

Docker Compose

  editor-ui:
    image: "lonelylockley/archinsight:editor-ui-latest"
    container_name: editor-ui
    hostname: editor-ui
    restart: always
    environment:
      - MICRONAUT_CONFIG_FILES=/etc/application.yml
      - JAVA_TOOL_OPTIONS=-Xms256M -Xmx256M
    networks:
      - archinsight
    volumes:
      - ./application.yml:/etc/application.yml:ro

Configuration Parameters

Parameter Description Default Value
micronaut.http.services.identity.url Base URL of the identity service http://identity:8080
micronaut.http.services.compiler.url Base URL of the translator service http://translator:8080
micronaut.http.services.renderer.url Base URL of the renderer service http://renderer:8080
micronaut.http.services.repository.url Base URL of the repository service http://repository:8080
archinsight.devMode Enables development mode false
archinsight.domain Base domain for the service (required)
archinsight.loginUrl Public login URL (required)
archinsight.identityAuthToken Authentication token for identity service (empty)
archinsight.translatorAuthToken Authentication token for translator service (empty)
archinsight.rendererAuthToken Authentication token for renderer service (empty)
archinsight.repositoryAuthToken Authentication token for repository service (empty)
archinsight.contextPath Base context path for UI routing /
archinsight.siteEnabled Enables the public site true 
micronaut:
  http:
    services:
      identity:
        url: 'http://identity:8080'
      translator:
        url: 'http://translator:8080'
      renderer:
        url: 'http://renderer:8080'
      repository:
        url: 'http://repository:8080'
archinsight:
  domain: '<PUBLIC_DOMAIN>'
  loginUrl: '<PUBLIC_URL>'
  identityAuthToken: '<SECRET_TOKEN>'
  translatorAuthToken: '<SECRET_TOKEN>'
  rendererAuthToken: '<SECRET_TOKEN>'
  repositoryAuthToken: '<SECRET_TOKEN>'

Environment Variables

Variable Description Default Value
IDENTITY Base URL of the identity service http://identity:8080
TRANSLATOR Base URL of the translator service http://translator:8080
RENDERER Base URL of the renderer service http://renderer:8080
REPOSITORY Base URL of the repository service http://repository:8080
DOMAIN Base domain of the application (required)
LOGIN Public login URL (required)
IDENTITY_TOKEN API authentication token for identity (empty)
TRANSLATOR_TOKEN API authentication token for translator (empty)
RENDERER_TOKEN API authentication token for renderer (empty)
REPOSITORY_TOKEN API authentication token for repository (empty)
JAVA_TOOL_OPTIONS JVM parameters (empty)
LOG_LEVEL Logback logging level info
MICRONAUT_CONFIG_FILES Path to service config (empty)
MICRONAUT_SERVER_PORT Port for the service to listen for connections 8080
DEV_MODE Runs service in development mode. Must never be enabled in production! false

3.6 Additional Configurations

Logging

If additional logging configuration is needed, a custom logback.xml file should be provided, added to JVM arguments and mounted within the container:

environment:
      - JAVA_TOOL_OPTIONS=-Dlogback.configurationFile=/etc/logback.xml
...
volumes:
      - ./logback.xml:/etc/logback.xml:ro

Security

All services are developed with basic security support using API Token authentication. For enhanced security, it is recommended to implement stronger measures such as mTLS. In such case security settings may be disabled and token parameters unset:

security:
  enabled: false
...
Quick Navigation