mcpringle/dukeops repository overview

⁠DukeOps

iJUG Self-Service Portal

⁠Table of Contents

• About⁠
• Versioning⁠
• Contributing⁠
• Communication⁠
  • Matrix Chat⁠
  • GitHub Discussions⁠
• Configuration⁠
  • Server Configuration⁠
  • Mail Configuration⁠
  • Database Configuration⁠
• Copyright and License⁠

⁠About

DukeOps is a self-service portal for iJUG members.

⁠Versioning

DukeOps follows Semantic Versioning 2.0.0⁠. Version numbers are structured as MAJOR.MINOR.PATCH:

• MAJOR versions introduce incompatible API or data changes,
• MINOR versions add functionality in a backwards-compatible manner,
• PATCH versions include backwards-compatible bug fixes.

This versioning scheme applies to the public API, database schema, and plugin interfaces. We aim to keep upgrades predictable and manageable. Breaking changes, new features, and fixes are documented in the CHANGELOG.md⁠ and in the release notes⁠.

⁠Contributing

You can find a lot of information on how you can contribute to DukeOps in the separate file CONTRIBUTING.md⁠. A curated list of contributors is available in the file CONTRIBUTORS.md⁠.

⁠Communication

⁠Matrix Chat

There is a channel at Matrix for quick and easy communication. This is publicly accessible for everyone. For developers as well as users. The communication in this chat is to be regarded as short-lived and has no documentary character.

You can find our Matrix channel here: @dukeops:ijug.eu⁠

⁠GitHub Discussions

We use the corresponding GitHub function for discussions. The discussions held here are long-lived and divided into categories for the sake of clarity. One important category, for example, is that for questions and answers.

Discussions on GitHub: https://github.com/ijug-ev/dukeops/discussions⁠
Questions and Answers: https://github.com/ijug-ev/dukeops/discussions/categories/q-a⁠

⁠Configuration

The file application.properties contains only some default values. To override the default values and to specify other configuration options, just set them as environment variables. The following sections describe all available configuration options. You only need to specify these options if your configuration settings differ from the defaults.

⁠Server Configuration

The server runs on port 8080 by default. If you don't like it, change it using an environment variable:

DUKEOPS_PORT=8080

⁠Instance Configuration

⁠Admin

When starting DukeOps, the system can automatically create instance admins. To enable this, set the following environment variable to a comma separated list of the email addresses of the admins:

[email protected]

If no user with the admin role is found in the database, a new instance admin will be created with the email address given.

⁠Mail Configuration

DukeOps supports sending email notifications. Configuration is done via environment variables using the DUKEOPS_MAIL_* naming scheme.

⁠Available Environment Variables

⁠Example Configuration

In a .env file, CI system, or Docker environment:

[email protected]
[email protected]
[email protected]
DUKEOPS_MAIL_HOST=smtp.example.com
DUKEOPS_MAIL_PORT=587
DUKEOPS_MAIL_USERNAME=myuser
DUKEOPS_MAIL_PASSWORD=secret
DUKEOPS_MAIL_SMTP_AUTH=true
DUKEOPS_MAIL_STARTTLS_ENABLE=true

⁠Database Configuration

DukeOps needs a database to store the business data. By default, DukeOps comes with MariaDB⁠ drivers. MariaDB is recommended because we are using it during development, and it is highly tested with DukeOps. All free and open source JDBC compatible databases are supported, but you need to configure the JDBC driver dependencies accordingly. Please make sure that your database is using a Unicode character set to avoid problems storing data containing Unicode characters. The database user to access the DukeOps database executes automatic schema migrations and needs ALL PRIVILEGES.

Please configure the database connection using the following environment variables:

DUKEOPS_DB_URL=jdbc:mariadb://localhost:3306/dukeops?serverTimezone\=Europe/Zurich&allowMultiQueries=true
DUKEOPS_DB_USER=johndoe
DUKEOPS_DB_PASS=verysecret

The database schema will be migrated automatically by DukeOps.

⁠Important MySQL and MariaDB configuration

MySQL and MariaDB have a possible silent truncation problem with the GROUP_CONCAT command. To avoid this it is necessary, to configure these two databases to allow multi queries. Just add allowMultiQueries=true to the JDBC database URL like in this example (you may need to scroll the example code to the right):

DUKEOPS_DB_URL=jdbc:mariadb://localhost:3306/dukeops?serverTimezone\=Europe/Zurich&allowMultiQueries=true

⁠Copyright and License

AGPL License⁠

Copyright (C) Marcus Fihlon and the individual contributors to DukeOps.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/⁠.