Admin Guide brix:corvus

Setup

In oder to run corvus, you'll need:

  • A recent version of Java (8 or higher)
  • An SQL database (whatever JDBC supports)
  • A storage location for templates and user files
  • A configuration file, e.g. application-example.yml

To start corvus, you'll need to provide the above configuration file as an argument:

java -jar corvus.jar --spring.profiles.active=default,example

Using default,example ensures that the default properties (built-in) are applied first, and then example overwrites the ones it specifies. That way, you don't have to add all of the properties to your file, only the ones you want to change. Here's an example of how a application-example.yml might look like:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/corvus?useUnicode=true&characterEncoding=utf8&useSSL=false
    username: corvus
    password: ********
  mail:
    host: localhost
    port: 2525
    test-connection: false
server:
  port: 8888
corvus:
  defaultLocale: de
  entryLocales: de,en,fr,it
  templateLocation: file:templates
  userFilesLocation: file:userfiles
  uiUrl: 'http://corvus.local'
  apiUrl: 'http://corvus.local/api'
  cors:
    allowedOrigin: 'http://corvus.local'
  debug:
    printStackTrace: false
logging:
  level:
    ch.brix.corvus: DEBUG

Service

In order to start corvus as a systemd service, put the following into /etc/systemd/system/corvus.service (adapt the paths and the profile):

[Unit]
Description=corvus
After=syslog.target network.target

[Service]
User=www-data
WorkingDirectory=/some/where/corvus
ExecStart=/usr/bin/java -jar /some/where/corvus/corvus.jar --spring.profiles.active=default,example
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

and execute a systemctl daemon-reload so that the new service is picked up.

You can now start the service through systemctl start corvus and have it start automatically with systemctl enable corvus

SSO

  • In your realm, create a new client (e.g. Client ID: corvus) with the protocol openid-connect

    • when using Keycloak, enable Standard Flow, Service Accounts and Authorization
  • Add a redirect URI to {corvus-server}/api/v1/oauth2/*

    • when using Keycloak, ensure that "Client Authorization" is set to "Client ID and Secret" in the Credentials section
  • In the backend, configure the following ("keycloak" is the expected registrationId/providerId for historical reasons). Most notably the client id and secret:
spring:
  security:
    require-ssl: true
    oauth2:
      client:
        registration:
          keycloak:
            client-id: corvus
            client-secret: ************************
            clientName: keycloak
            authorization-grant-type: authorization_code
            redirectUriTemplate: 'http://corvus.local/api/v1/oauth2/callback/{registrationId}'
            scope:
              - openid
              - profile
              - email
        provider:
          keycloak:
            authorization-uri: https://your.sso.server/auth/realms/mybrix/protocol/openid-connect/auth
            token-uri: https://your.sso.server/auth/realms/mybrix/protocol/openid-connect/token
            user-info-uri: https://your.sso.server/auth/realms/mybrix/protocol/openid-connect/userinfo
            jwk-set-uri: https://your.sso.server/auth/realms/mybrix/protocol/openid-connect/certs
            issuer-uri: https://your.sso.server/auth/realms/mybrix
            user-name-attribute: preferred_username

For Keycloak, you can find these URLs in {keycloak-url}/auth/realms/{realm-name}/.well-known/openid-configuration

For Azure, you can find these URLs in https://login.microsoftonline.com/{tennant-id}/.well-known/openid-configuration

  • Configure the attributes that should be transferred (i.e. username, e-mail, roles etc.) on the IdP

  • Configure the attribute mapping in corvus:

    corvus:
    sso:
    import:
      attributes:
        username: preferred_username
        firstname: given_name
        lastname: family_name
        email: email
        roles: roles
        locale: locale
        mappingBean: KeycloakUserMapping
    redirect:
      frontend:
        fragment: "/#/login?token="

Frontend

Configure the frontend in the environment-file (./src/environments.ts)

export const environment = {
    retryIn: 5,
    production: false,
    api_path:  '',
    title : '',
    whitelistedDomains: [],
    blacklistedRoutes: [],
    customFavicon : true,
    anuraNodeIdKey : '',
    entries_per_page: 10,
    supporteLanguages: [
        {
            'display': 'English',
            'value': 'en'
        },
        {
            'display': 'Deutsch',
            'value': 'de'
        },

        {
            'display': 'Italienisch',
            'value': 'it'
        },
        {
            'display': 'Spanisch',
            'value': 'es'
        },
        {
            'display': 'Französch',
            'value': 'fr'
        }
    ],
    'files': 'files',
    'themes': [
        {
            'name': 'cosmo',
            'file': 'bootstrap.cosmo.min.css'
        },
        {
            'name': 'darkly',
            'file': 'bootstrap.darkly.min.css'
        },
        {
            'name': 'flatly',
            'file': 'bootstrap.flatly.min.css'

        }
    ],
    files_path: 'files/',
    entry_path: 'entry/',
    settings_path: 'settings/',
    templates_path: 'templates/',
    output_channels_path: 'outputchannels/',
    role_path: 'roles/',
    workflow_path: 'workflows/',
    notifications_path: 'messages/',
    user_path: 'users/',
    translation_path: 'translation/',
    fileUpload_path: 'files/upload',
    spellcheck_path: 'spellcheck/',
    subscription_path: 'subscription/',
    output_intents_path: 'outputintents/',
    login_path: 'login/',
    test_path: 'test/',
    jobs_path: 'job/',
    webbaukasten_path: 'nak/webbaukasten/'
};

Configure your custom style in the custom css-file (./assets/custom/styles.css)

Compile your project like this:

  1. npm install
  2. ng build (ng build --configuration )