Open Source Community Manager
Komunumo is an esperanto noun with a meaning of community.
The server of Komunumo is written using the Java programming language. The main framework is Spring. For the user interface, we use Vaadin Flow. To access the database, we rely on jOOQ. To coordinate the build process, Maven is used.
Vaadin web applications are full-stack and include both client-side and server-side code in the same project.
| Directory | Description |
|---|---|
src/main/frontend/ |
Client-side source directory |
index.html |
HTML template |
index.ts |
Frontend entrypoint |
main-layout.ts |
Main layout Web Component (optional) |
views/ |
UI views Web Components (TypeScript / HTML) |
styles/ |
Styles directory (CSS) |
src/main/java/org/komunumo/ |
Server-side source directory |
Application.java |
Server entrypoint |
AppShell.java |
application-shell configuration |
- Read the documentation at vaadin.com/docs.
- Follow the tutorials at vaadin.com/tutorials.
- Watch training videos and get certified at vaadin.com/learn/training.
- Create new projects at start.vaadin.com.
- Search UI components and their usage examples at vaadin.com/components.
- View use case applications that demonstrate Vaadin capabilities at vaadin.com/examples-and-demos.
- Discover Vaadin's set of CSS utility classes that enable building any UI without custom CSS in the docs.
- Find a collection of solutions to common use cases in Vaadin Cookbook.
- Find Add-ons at vaadin.com/directory.
- Ask questions on Stack Overflow or join our Discord channel.
- Report issues, create pull requests in GitHub.
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.
The server runs on port 8080 by default. If you don't like it, change it:
PORT=8080
Komunumo needs a database to store the business data. By default, Komunumo comes with MariaDB drivers. MariaDB is recommended because we are using it during development, and it is highly tested with Komunumo. 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 DB_USER is used to access the Komunumo database including automatic schema migrations and needs ALL PRIVILEGES.
DB_URL=jdbc:mariadb://localhost:3306/komunumo?serverTimezone\=Europe/Zurich&allowMultiQueries=true
DB_USER=johndoe
DB_PASS=verysecret
The database schema will be migrated automatically by Komunumo.
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):
DB_URL=jdbc:mariadb://localhost:3306/komunumo?serverTimezone\=Europe/Zurich&allowMultiQueries=true
The old website runs on a server at Metanet. All the existing data needs to be imported to Komunumo once at go-live. This is done by querying the old database. To run the import, the following configurations need to be set:
METANET_DATABASE_URL=jdbc:mariadb://remotehost:3306/database?serverTimezone\=Europe/Zurich&allowMultiQueries=true
METANET_DATABASE_USER=janedoe
METANET_DATABASE_PASSWORD=verysecred
When these settings are not blank, the import will start automatically ten seconds after the launch of Komunumo.
Every website needs some basic configuration. Have a look at the following configuration options, most of which are self-describing:
WEBSITE_URL=http://localhost:8080
WEBSITE_ASSOCIATION=User Group Name
WEBSITE_ABOUT_TEXT=Tell the world what this user group is about.
WEBSITE_CONTACT_ADDRESS=12345 Foobar
WEBSITE_CONTACT_EMAIL=noreply@localhost
WEBSITE_COPYRIGHT=© User Group Name
WEBSITE_LOGO_TEMPLATE=http://localhost/images/logo_%02d.png
WEBSITE_LOGO_MIN=1
WEBSITE_LOGO_MAX=10
Note
The configuration option WEBSITE_ABOUT_TEXT is allowed to contain HTML code! So you can use paragraphs and links, if needed.
Important
The logo handling is very special: If you want to specify only one logo, just use the URL and set the MIN and MAX values to 0. Done. But if you want Komunumo to pick a random logo on every request, you can specify a logo template which must contain a String format argument for a decimal integer representation (like %02d for a two-digit number in the example above). In addition, set the MIN and MAX values as needed. Komunumo will randomly pick a number between the provided MIN and MAX values (both included) and merge it with the provided TEMPLATE to create the image URL.
Komunumo uses Maven to build the project. Please use standard Maven commands to build what you need:
| Command | What it does |
|---|---|
./mvnw |
compile and run the app |
./mvnw clean |
cleanup generated files and build artefacts |
./mvnw compile |
compile the code without running the tests |
./mvnw test |
compile and run all tests |
./mvnw package |
compile, test, and create a JAR file to run it with Java directly |
./mvnw verify |
compile, test, package, and run analysis tools |
There is no need to run the install or deploy tasks. They will just run longer, produce unnecessary output, burn energy, and occupy your disk space. Don't just blindly run mvn clean install...
Komunumo comes with a complete dockerized build for production use. It is not recommended to use the self-contained build for development purposes. Please take a look at the section about Production Build below.
There are two ways to run the application: From the command line or directly from your IDE.
To run from the command line, use ./mvnw and open http://localhost:8080 in your browser.
- On the right side of the window, select "Maven" --> "Plugins" -->
spring-boot-->spring-boot:run - Optionally, you can disable tests by clicking on a
Skip Tests modeblue button.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Locate the
Application.javaclass in the Project view. It is in thesrcfolder, under the main package's root. - Right-click on the Application class
- Select "Debug 'Application.main()'" from the list
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Right click on a project folder and select
Run As-->Maven build.... After that a configuration window is opened. - In the window set the value of the Goals field to
spring-boot:run - You can optionally select the
Skip testscheckbox - All the other settings can be left to default
Once configurations are set clicking Run will start the application.
Do not worry if the debugger breaks at a SilentExitException. This is a Spring Boot feature and happens on every startup.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Locate the
Application.javaclass in the Package Explorer. It is insrc/main/java, under the main package. - Right-click on the file and select
Debug As-->Java Application.
Do not worry if the debugger breaks at a SilentExitException. This is a Spring Boot feature and happens on every startup.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
To build the Dockerized version of the project, run
docker build . -t komunumo:latest
Once the Docker image is correctly built, you can test it locally using
docker run -p 8080:8080 komunumo:latest
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: @komunumo:ijug.eu
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/McPringle/komunumo/discussions
Questions and Answers: https://github.com/McPringle/komunumo/discussions/categories/q-a
To find possible tasks for your first contribution to Komunumo, we tagged some of the hopefully easier to solve issues as good first issue.
If you prefer to meet people in real life to contribute to Komunumo together, we recommend to visit a Hackergarten event. Komunumo is often selected as a contribution target in Lucerne, Zurich, and at the JavaLand conference.
Please join our developer community using our Matrix chat to get support and help for contributing to Komunumo.
It is important to sign-off every commit. That is a de facto standard way to ensure that you have the right to submit your content and that you agree to the DCO (Developer Certificate of Origin).
You can find more information about why this is important and how to do it easily in a very good blog post by Josef Andersson.
We love to add an emoji to the beginning of every commit message which relates to the nature of the change. You can find a searchable list of possible emojis and their meaning in the overview on the gitmoji website. If you prefer, you can also install one of the plugins that are available for almost all common IDEs.
AI generated source code is based on real existing source code, which is copied in whole or in part into the generated code. The license of the original source code with which the AI was trained is not taken into account. It is not clear which license conditions apply and how these can be complied with. For legal reasons, we therefore do not allow AI-generated source code at all.
Special thanks for all these wonderful people who had helped this project so far (emoji key):
 Marcus Fihlon 📆 🤔 💻 🎨 |
 Interactiondesigner 🎨 |
 Knoobie 💻 |
 Shree Gillorkar 💻 |
Copyright (C) Marcus Fihlon and the individual contributors to Komunumo.
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/.