Improve setup instructions

[ariostas]

I fixed the instructions for the setup with apptainer and I added a brief mention of what to do if using Docker Engine instead of Docker Desktop.

I still need to add instructions for setting up OpenSearch with apptainer.

[michmx]

Thanks a lot for the nice improvement!

[michmx]

@ariostas Did you set it as Draft only because of the OpenSearch part?

[ariostas]

Yeah, I haven't been able to get OpenSearch to work on Apptainer. Here are the steps I have so far:

mkdir /scratch/<username>/opensearch-apptainer; cd /scratch/<username>/opensearch-apptainer
mkdir -p ./opensearch/logs
apptainer pull --name opensearch.sif docker://opensearchproject/opensearch:latest
apptainer exec --bind ${PWD}/opensearch:/usr/share/opensearch/defaultconfig ./opensearch.sif cp -r /usr/share/opensearch/config /usr/share/opensearch/defaultconfig
apptainer instance start --bind ${PWD}/opensearch/logs:/usr/share/opensearch/logs --bind ${PWD}/opensearch/config:/usr/share/opensearch/config ./opensearch.sif opensearch
apptainer exec --env discovery.type=single-node --env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> instance://opensearch /usr/share/opensearch/opensearch-docker-entrypoint.sh

However, there is a Java error in the last step that I haven't been able to get around.

[ariostas]

Just to follow up on this, here are some updated instructions that get almost to the end of the OpenSearch setup with Apptainer.

mkdir /scratch/<username>/opensearch-apptainer; cd /scratch/<username>/opensearch-apptainer
apptainer pull --name opensearch.sif docker://opensearchproject/opensearch:latest
apptainer instance start --writable-tmpfs ./opensearch.sif opensearch
export OPENSEARCH_INITIAL_ADMIN_PASSWORD="<custom-admin-password>"
apptainer exec instance://opensearch /usr/share/opensearch/opensearch-docker-entrypoint.sh

The problem is that it fails some checks while initializing things.

ERROR: [2] bootstrap checks failed
[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
[2]: the default discovery settings are unsuitable for production use; at least one of [discovery.seed_hosts, discovery.seed_providers, cluster.initial_cluster_manager_nodes / cluster.initial_master_nodes] must be configured

The first one requires root permissions on the host machine (or skipping the check somehow). The second one is also tricky since setting environment variables with a dot is disallowed and requires sketchy workarounds.

I think that the best alternative is to either mention that the OpenSearch part can only be done with Docker, or to switch to something else like MongoDB that is easier to set up on Apptainer.

[ariostas]

@michmx how would you feel about removing mentions of Apptainer and instead I can set up a config file for GitHub codespaces and add instructions in the setup page so that people can just follow the tutorial there with Docker? That way they only need to have a GitHub account and they don't need to worry about installing Docker or anything