Install Peaksel

Specs

  • Operating System: Ubuntu with Docker installed. Windows is supported, but not recommended.

  • Required software: Docker and Docker Compose Plugin (see instructions below)

  • Authentication: if you have a corporate OAuth2 OpenID Connect server, Peaksel can use that. Otherwise, you can configure the user list in the configuration file. See User Management.

Hardware requirements will depend mostly on how many users and how much data you have. You can start with the minimal

Minimum Optimal

CPU

1

8

RAM

2

16

Disk

HDD

SSD

Disk size

100GB

Depends on the amount of data you have

Installation options

Ubuntu/Debian with Docker (recommended)

This instruction will guide you to install Peaksel as well as its database (PostgreSQL) as Docker containers. You may want to consider installing and managing database separately for production use.

  1. Install Docker using official docs on Ubuntu

  2. Run docker login on Ubuntu (email us and we’ll provide the credentials)

  3. Download and unzip Peaksel configs. There are 3 places where it’s advisable to change passwords:

    • 1 password in init.sql

    • 2 passwords in docker-compose.yml: db.pass must the same as the password in init.sql, while POSTGRES_PASSWORD can be anything

    • Don’t change any usernames

  4. Edit docker-compose.yml and replace !PUT VERSION HERE! with a real version that you received from us via email

  5. Step into the folder in the terminal and run docker compose up -d

  6. Now you can open it in your browser: http://[ip-address-of-ubuntu-machine]:8080

Besides Peaksel itself, this starts Postgres DB inside as a Docker container too. If you want more scalable/reliable set up, you may want to consider setting up Postgres on a separate machine with backups & failover set ups. Or use cloud versions.

Windows w/o Docker (not recommended)

This isn’t a recommended option for production work and should be used only to evaluate Peaksel.

Before installing Peaksel itself we need to install its dependencies:

  1. Download latest Java (at the time of writing it was Java23), unzip it into one of your software folders, let’s say C:\Users\[your user]\Documents\elsci\. Your Java Home path should be something like this: C:\Users\[your user]\Documents\elsci\openjdk-23_windows-x64_bin\jdk-23.

  2. Download and install latest PostgreSQL. Remember which password you configured, choose locale English, United States.

Now install and configure Peaksel:

  1. Download and unzip Peaksel configs into C:\Users\[your user]\Documents\elsci

  2. Open peaksel.bat in notepad and edit first lines: specify where your Java location is, where PostgreSQL is installed and what was the password that you entered during Postgres installation.

  3. Download Peaksel from the URL that we provided in the email.

  4. Rename it to peaksel.jar and put it into C:\Users\[your user]\Documents\elsci

  5. Open Windows Command Line (press Cmd+R, enter cmd) and run

cd Documents\elsci
peaksel.bat

  1. In 30 seconds open http://localhost:8080 in browser

  2. To stop Peaksel press Ctrl+C in Command Line

Upgrade

If you used Docker for the installation, all you need to do is:

  1. Update Peaksel version in docker-compose.yml

  2. docker compose pull (optional, downloads the new version so that the next command executes with minimal downtime)

  3. docker compose up -d

Troubleshooting

Locked database

Peaksel doesn’t start and the logs say:

liquibase.lockservice - Waiting for changelog lock....
liquibase.lockservice - Waiting for changelog lock....
...

All you need is:

  1. Ensure there’s just one Peaksel instance running (docker ps)

  2. docker exec -u postgres -it peakseldb psql elsci -c "delete from peaksel.databasechangeloglock"

Explanation

When Peaksel starts it may need to do some database maintenance (we call it "DB Migration", and we use Liquibase for this). But we must be sure 2 Peaksel instances don’t access the same DB simultaneously for this.

To enable this there’s a table databasechangeloglock. When Peaksel starts, it first tries to insert/update a row with locked=true. If such row already exists, then there’s another Peaksel instance doing it already. And the current instance has to stop and wait. In the end the row is deleted or marked as locked=false, and so the 2nd instance proceeds.

But what if we started Peaksel and stopped it right in the middle of the DB Migration? Then the lock isn’t getting deleted - it stays in the table forever. And when you start Peaksel it thinks that someone else is running a DB migration, and so it keeps waiting forever.

The solution above deletes such a lock, allowing Peaksel to proceed. The anatomy of the command:

docker exec -u [docker user, must be postgres] -it [docker container] psql [db name] -c "delte from [db schema].databasechangeloglock"

There are better approaches to do such locking, e.g. used by Flyway, we may switch to it at some point. But it’s not easy, so no ETA for now.