If you're looking for installation or management documentation, see the documentation folder.
The project is a multimodule project where we've separated the REST API to api
module, while the server code
is in service
module.
The application functionality documentation can be found in the documentation folder.
We use maven-enforcer-plugin to ensure we're not
importing multiple versions of the same module or library to the build. To activate the enforcer-plugin, run the
verify
stage, like so:
./mvnw clean verify
This will fail, with details, if there are multiple versions of the same module.
Most of the endpoints require that you authenticate yourself first. Click on the Authorize
button located in the upper
right corner.
The service can be run locally by starting the PostgreSQL server with the script db_local_setup.sh
.
The script will clean up any previous docker container and volume, so you always have a fresh, empty database available.
When the database is up and running, you can start up the service itself with the command:
./mvnw clean test spring-boot:run
This will generate the necessary schema and tables. Once the service is up and running, you can complete the setup
by running create_local_users.sh
. This will use the test.sql
which injects a couple of users as well as a some events in the future into the database so that the local installation
can be logged onto and tested manually. The user details are in the file.
Alternatively you can use a larger dataset, located in test-large.sql
which contains
several thousand users and hundreds of events. This dataset has been generated with the test facility which is only
available when running the service locally. To use the large dataset, you run the command as follows:
cat test-data/test-large.sql | psql --host=localhost --port=5432 --username oxalate oxdb
Once the above are up and running, you can start the frontend locally. See the README.md for details.
The file contains also some pre-generated audit events which have been generated with the following command:
for i in $(seq 1 60); do
echo "('$(uuidgen)','INFO',$((1 + $RANDOM % 100)), '1.2.3.4', 'TestController','Test message',NOW()-INTERVAL '$((1 + $RANDOM % 40)) DAYS'),"
done
After which some of the INFO-level messages were changed to ERROR- and WARN-level messages.
The local setup is simple, we use a default PostgreSQL instance with postgre-user and no password. These settings come from the local.yaml.
All the events are either in the future, or the past. If you need to test with an ongoing event (using the large dataset), run the following command:
UPDATE events
SET event_duration = 12,
start_time = NOW() - INTERVAL '1 hour'
WHERE id IN (7, 8, 9);
When running the service locally, an additional REST API is available in Swagger UI.
The /api/test/users
takes a single parameter, numberOfUsers
and then generates that many users into the database.
The /api/test/events
takes a single parameter, numberOfYears
and then generates that events, users and payments into the database for given number of years.
Note that this process may not be very fast, generating 5 years of activity will take around 10 minutes. If you need larger number of events, then consider
using the data in test-large.sql
instead.
With the large dataset, every user has the same password, aA1^WWWWWWWWW
. Some more useful users are:
Username | Password | Role |
---|---|---|
[email protected] | aA1^WWWWWWWWW | USER, ORGANIZER, ADMIN |
[email protected] | aA1^WWWWWWWWW | USER, ADMIN |
[email protected] | aA1^WWWWWWWWW | USER, ORGANIZER |
[email protected] | aA1^WWWWWWWWW | USER, ORGANIZER |
[email protected] | aA1^WWWWWWWWW | USER |
By default, mail sending (SMTP) is not enabled on local environment.
In this case emails sent by system are logged on INFO
level.
It is also possible to set up local mail server, for example by starting a catch-all server container with following command:
docker run --rm -it -p 3001:80 -p 2525:25 rnwood/smtp4dev:v3
In addition to that change oxalate.mail.enabled
variable to true
in local.yaml
config file.
See CODESTYLE.md and CONVENTIONS.md
GHA has been enabled in the repository. Current version is very rudimentary, it merely checks out the code, and runs the small set of existing tests. Nonetheless, it is a good start, and it can be extended to run more tests, and to build the docker image.
GHA is configured to run on every pull request. The build has to be green in order that the PR can be merged.
Dependabot is enabled for this repository. It will automatically create pull requests to update dependencies when new versions of maven dependency modules
are released. The pull requests are created to the dependabot
branch, and they need to be merged manually. The pull requests are created automatically
when new versions are released. The scheduling of dependabot is on weekly basis.
Each pull request should be investigated locally, and any additional commits should be annotated with [dependabot]
-prefix.
This code is published under the GPL 2 License.
- Mikko Mustonen, founder, (Frontend, Backend)
- Paul-Erik 'Poltsi' Törrönen, developer, (Frontend, Backend)