As user I want all I need to start Armadillo on README.md

[mswertz]

Shortest description how to start is on in README. (as it used to be). Link to docs for the details

[clemens-tolboom]

Something like a quick start?

I need some context for that:

• As a desktop user
• Linux server user?
• Requiring java?
• Using armadillo-compose https://github.com/molgenis/molgenis-service-armadillo/releases/tag/v4.2.7
• Requiring docker?

I would opt for armadillo-compose as that only requires shell + docker

What do you think?

[clemens-tolboom]

Running Armadillo locally using armadillo-compose.zip

You can choose either the latests build version (pre release) or the official (stable) release.

These steps require Docker Desktop installed as the profiles require it and this version of Armadillo needs it.

1. From the chosen version page at the Assets section download armadillo-compose.zip
2. Unzip the file ... directory armadillo-compose is extracted
3. Open a terminal in the armadillo-compose directory
4. Run docker compose build (or docker-compose using depending on OS)
5. Run docker compose up (to stop later on press CTRL-C)
6. Navigate to http://localhost:8080
7. Login using basic auth with user admin and password admin

For more info about editing the configuration and cleanup read the supplied README.md file

[clemens-tolboom]

Findings ✅

Linux ✅

• ${PWD} does not work on Linux ... use ./ instead (project/profiles/etc not found) fixed by #690
• Via UI config is not config is not editable (user running containers is not current (using sudo) nor root) solved by the above
• ?

Release test script ✅

We were testing against v4.1.3 which did not support linked view yet. used wrong version

── Creating linked view on table ──

Created project 'qlzvezj3v9' without users
✖ 
Error in stop(cond) : bad error message
Calls: exit_test
Execution halted

[clemens-tolboom]

Run Armadillo using the Dockerfile

---

Run the Dockerfile

Steps

To run the Dockerfile you first need to

1. Make directory demo-armadillo and cd into demo-armadillo
2. Make sub directories data config logs
   1. You can add configuration by downloading application.template.yml and move it to `confg/application.yml
3. Download the Dockerfile
4. Download the molgenis-armadillo-*.jar file from the assets of latest or one of the other releases

Shell prepare

mkdir demo-armadillo
cd demo-armadillo
mkdir data config logs

wget https://raw.githubusercontent.com/molgenis/molgenis-service-armadillo/master/Dockerfile

# change name and version to your likings
wget https://github.com/molgenis/molgenis-service-armadillo/releases/download/v4.3.1/molgenis-armadillo-4.3.1.jar

# Not needed unless
wget https://raw.githubusercontent.com/molgenis/molgenis-service-armadillo/master/application.template.yml --output-document=config/application.yml

Build a local image

# Change name or version
docker build --tag demo_armadillo:local --build-arg JAR_FILE="./*.jar" .

Run the container

docker run \
  --detach \
  --publish 8080:8080 \
  --volume ./data:/data \
  --volume ./config:/config \
  --volume ./logs:/logs \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --name demo_armadillo \
  demo_armadillo:local

Container life cycle

docker container stop demo_armadillo
docker run ...

Cleanup

docker container rm demo_armadillo
docker image ls
docker image rm <hash of demo_armadillo>

[clemens-tolboom]

• Check with EMX2 for adding files to Docker image
• make 2 /docs/ documents for each variant
• cleanup README.md
  • keep opening line
  • make list of feature of the bold text
• Add QuickStart section
  • Link to "Using Armadillo compose" with text like "Install docker, unzip the zip, type shell commands"
  • Link to "Using Dockerfile" with text like "Install docker, run shell commands to fetch requirements, run"

[clemens-tolboom]

Using the jar file

• Install Java from https://jdk.java.net shows version 22
  • brew install openjdk gives version 21
  • winget ?
• Install Docker Destop

To test as a new user remove all related docker containers and images and stop docker daemon

mkdir test
cd test
wget https://github.com/molgenis/molgenis-service-armadillo/releases/download/v4.5.0/molgenis-armadillo-4.5.0.jar

java -jar molgenis-armadillo-4.5.0.jar
# fails on missing docker daemon: 
# - Error creating bean with name 'profilesDockerController'
# - install Docker Desktop and run it
java -jar molgenis-armadillo-4.5.0.jar
# fails on missing data dir

mkdir data
java -jar molgenis-armadillo-4.5.0.jar
# Check projects (empty)
# Check users (empty)
# Check profiles (default datashield/rock-base:latest)
# Check insight file audit exists
# Check insight file Log is empty
CTRL-C

ls -l
# data/
# logs/
# molgenis-armadillo-4.5.0.jar
# - logs/ dir is created automagically