Skip to content

Latest commit

 

History

History
215 lines (156 loc) · 7.32 KB

DEVELOPMENT.md

File metadata and controls

215 lines (156 loc) · 7.32 KB

Development

Build

You will need Java 17 and Maven 3.9 then execute

mvn clean install
mvn quarkus:dev -pl 'horreum-backend'

Example data

You can preload Horreum with some example data with

./infra-legacy/example-configuration.sh

once Horreum is running.

OpenAPI

The OpenAPI for Horreum will be located in

./horreum-api/target/generated/openapi.yaml

after the build.

The website is hosting a copy of the OpenAPI reference.

Main configuration

The main configuration of Horreum is in the application.properties file.

The database bootstrap script is in the changeLog.xml

Releases

Horreum is pre-1.0 (0.y.z) and therefore we cannot guarantee binary compatability between patch releases (0.y.z to 0.y.z+1). We plan to increase minor versions (y values) when breaking APIs but API breaking bug fixes might appear in patch releases. semver clause

Credentials

Horreum is running on localhost:8080

Role Name Password
User user secret

Messaging

By default Horreum uses SmallRye Messaging and for example Apache Artemis has the messaging platform.

In the case of Apache Artemis the key is to configure the setup to work against the application.properties file.

So, for example:

Create a user

artemis user add

to add the horreum user - default password is secret.

So in artemis-roles.properties

horreum = horreum

In broker.xml

      <security-settings>
         <security-setting match="#">
            <permission type="createNonDurableQueue" roles="amq, horreum"/>
            <permission type="deleteNonDurableQueue" roles="amq, horreum"/>
            <permission type="createDurableQueue" roles="amq, horreum"/>
            <permission type="deleteDurableQueue" roles="amq, horreum"/>
            <permission type="createAddress" roles="amq, horreum"/>
            <permission type="deleteAddress" roles="amq, horreum"/>
            <permission type="consume" roles="amq, horreum"/>
            <permission type="browse" roles="amq, horreum"/>
            <permission type="send" roles="amq, horreum"/>
            <permission type="manage" roles="amq, horreum"/>
         </security-setting>
      </security-settings>

and

      <addresses>
         <address name="DLQ">
            <anycast>
               <queue name="DLQ" />
            </anycast>
         </address>
         <address name="ExpiryQueue">
            <anycast>
               <queue name="ExpiryQueue" />
            </anycast>
         </address>
         <address name="dataset-event">
            <multicast>
               <queue name="horreum-broker.dataset-event"/>
            </multicast>
         </address>
         <address name="run-recalc">
            <multicast>
               <queue name="horreum-broker.run-recalc"/>
            </multicast>
         </address>
      </addresses>

Look at the Apache Artemis documentation for more information.

Access Keycloak

You can access the Keycloak instance by using the URL provided by the

curl -k -s http://localhost:8080/api/config/keycloak | jq -r .url

command.

The following users are defined

Role Name Password Realm
Admin admin secret
User user secret horreum

Troubleshooting development infrastructure

  1. Clean cached files and rebuild
$ mvn clean -p remove-node-cache
$ mvn clean install -DskipTests -DskipITs

Local development with Podman

Podman 4 can be used for the development mode of Horreum.

Install of the podman packages:

dnf install -y podman podman-plugins podman-docker

In one terminal do

podman system service -t 0

And then configure DOCKER_HOST environment variable to resolve to the podman socket

export DOCKER_HOST=unix:///run/user/${UID}/podman/podman.sock

and use the standard build commands.

Using an existing backup

You can use an existing backup of the database (PostgreSQL 13+) by a command like

mvn  quarkus:dev -pl '!horreum-integration-tests' \
  -Dhorreum.dev-services.postgres.database-backup=/opt/databases/horreum-prod-db/ \
  -Dhorreum.dev-services.keycloak.db-password='prod-password' \
  -Dhorreum.dev-services.keycloak.admin-password='ui-prod-password' \
  -Dquarkus.datasource.username=user \
  -Dquarkus.datasource.password='prod-password' \
  -Dquarkus.liquibase.migration.migrate-at-start=false

or by placing a horreum-backend/.env file with content like

horreum.dev-services.postgres.database-backup=<path/to/db>
horreum.dev-services.keycloak.image=quay.io/keycloak/keycloak:20.0.1
horreum.dev-services.keycloak.db-username=<keycloak-user-name>
horreum.dev-services.keycloak.db-password=<keycloak-user-password>

horreum.dev-services.keycloak.admin-username=<keycloak-admin-name>
horreum.dev-services.keycloak.admin-password=<keycloak-admin-password>

quarkus.datasource.username=<horreum-user-name>
quarkus.datasource.password=<horreum-user-password>

# Set to `true` to migrate database schema at startup
quarkus.liquibase.migration.migrate-at-start=true
quarkus.liquibase.migration.validate-on-migrate=false

# Need user account with access to public schema
quarkus.datasource.migration.username=<migration-user-name>
quarkus.datasource.migration.password=<migration-user-password>

Backports

When developing new features, we always create pull requests (PRs) in the master branch. However, we always support the latest stable branch. If you encounter an issue that requires a fix for the stable branch, you can add the backport (or backport-squash) label to the original PR and a new PR will be automatically generated. You will then need to review and merge the backport PR.

Which label should I use?

  • backport: (default) this uses the no-squash=true option so that the tool tries to backport all commits coming from the original pull request you are trying to backport.

Note that in this case the commit SHAs should exist during the backporting, i.e, delete the source branch only after the backporting PR got created.

  • backport-squash: with this label you set no-squash=false option, so that the tool tries to backport the pull request merge_commit_sha.

Note the value of the merge_commit_sha attribute changes depending on the state of the pull request, see Github doc for more details.