Installation

Prerequisites

Java 17

Databucket server runs on Java 17 or newer.

PostgreSQL database

Databucket works only with a PostgreSQL server; it relies on PostgreSQL features (jsonb, triggers). The current version is developed and tested on PostgreSQL 18. Before configuration, create an empty database dedicated only to Databucket, and a user that owns it.

Databucket server JAR file

Download the latest Databucket server release from the Releases page, or build it yourself as described in the README.md. The JAR contains both the server and the web application.

Configuration

Before you run Databucket server using the databucket-server-3.x.x.jar file, prepare a configuration file and save it as application-profile_name.yaml in the directory you run Databucket from, where profile_name is the name used in the run command. You can keep several such files with different profile names, e.g. application-test.yaml and application-prd.yaml, and use one or the other depending on your needs.

Here you can see an example base configuration:

jwt:
  secret: change-me-to-a-random-text-of-at-least-32-characters # signs the users' sign-in tokens
  expire.hours: 24 # how long a sign-in is valid

server:
  port: 8080 # Databucket server port
  servlet.context-path: / # Databucket url suffix. If your base Databucket url is localhost:8080/test, then this path should be set as /test

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/databucket # PostgreSQL connection string
    username: username # database user name
    password: userpassword # database user password

jwt.secret must be at least 32 characters long, otherwise signing in fails. Generate a random one, e.g. with openssl rand -base64 48. Changing it later signs out all users. When you run several Databucket instances, all of them must use the same secret.

Optional settings

• Emails (registration confirmation, account activation, forgot password links and temporary passwords) are sent through the SMTP server configured in spring.mail:

spring:
  mail:
    host: smtp.example.com
    port: 587
    username: username
    password: password
    from: databucket@example.com
    properties.mail.smtp.auth: true
    properties.mail.smtp.starttls.enable: true

• Single sign-on with Microsoft Entra ID, Google, Okta, Keycloak or another OpenID Connect provider — see Single sign-on.

Every property can also be set as an environment variable instead of in the file, e.g. SPRING_DATASOURCE_PASSWORD or JWT_SECRET. This is handy for passwords and secrets.

Running

Suppose you have the following files in your directory:

• application-prd.yaml
• databucket-server-3.7.0.jar

Then, from the command line, run:

java -Dspring.profiles.active=prd -jar databucket-server-3.7.0.jar

Open http://localhost:8080 (with your port and context path) in the browser.

Database initialization

The database is initialized during the first Databucket startup. In this process, the application creates the required tables and a default user account with the SUPER role. Use this account to create your personal account. After that, disable the default user. Don't delete it: Databucket would create it again with the default password on the next startup.

Default user credentials:

• User name: super
• User password: super

Upgrading

1. Back up the database.
2. Stop Databucket and replace the JAR file with the new one.
3. Run the upgrade scripts of the versions you are skipping, in order, as listed below.
4. Start Databucket. New tables and columns are added automatically during startup.

The scripts are in the upgrade directory of the repository. Run them with psql:

psql -h <host> -U <user> -d <database> -f 3.7.0.sql

Each script runs in one transaction and can be run more than once.

Version	Script	What it does
3.7.0	3.7.0.sql	User emails must be unique (single sign-on matches users by email). The script stores the emails trimmed and lower-cased and adds the unique constraint. When several users share an email, it lists them and changes nothing. Give each of them a unique email (or clear it) and run the script again.
3.7.1	—	No database changes. Replace the JAR file.
3.7.2	—	No database changes. Replace the JAR file.

A new, empty database doesn't need any scripts.