eSASS installation

The eROSITA Science Analysis Software System (eSASS) is distributed in a tgz file for Ubuntu systems. eSASS is also distributed in a Docker-container, which can be used on macOS, Windows and other Linux distributions. Directions on how to download, install and use eSASS and the Docker-container can be found in the following.

On this page

1 Dowloading eSASS and the eROSITA calibration database (CALDB)

The eSASS package and the eROSITA calibration database are available at: 

To download their contents, first, download the script After downloading, confirm that the script is executable (the script can be done executable by typing chmod +x Then, the script must be executed in a bash terminal:

 $ ./

Executing this script will mirror all or parts of the eSASS4EDR-download area to your local disk. The script accepts the following command-line options:

If for instance you are not interested in the demo script, you could execute the following:

 $ cd /<my eSASS path>
 $ ./ eSASS
 $ ./ CALDB

After downloading, you should have this directory structure on your disk:

 /<my eSASS path>/caldb
 /<my eSASS path>/demo
 /<my eSASS path>/sw_edr
 /<my eSASS path>/external
 /<my eSASS path>/ 

2 Installing eSASS on Linux (mostly Ubuntu systems)

2.1 Creating the eSASS directory structure

Go to directory /<my eSASS path>/ and execute the following command:

 $ ./ eSASS4EDR sw_edr

This will extract the full eSASS directory structure from the eSASS task archive in directory eSASS4EDR.

2.2 Building eSASS on x86_64 Linux: GNU autoconf build

Initial considerations
Configuring Healpix software

Start by building the Healpix software package, provided with eSASS. Go to directory

 $ cd /<my eSASS path>/external/Healpix_3.50 

and launch the configure script there:

  1. Choose option "3": configure Healpix F90 package.
  2. Enter the name of your F90 compiler (e.g., gfortran).
  3. Accept all default flags.
  4. Enter the name of your C compiler (e.g., gcc).
  5. Accept all default flags.
  6. Accept for the libcfitsio.a library.
  7. Point to your CFITSIO library (the command locate can be used to find the directory ~/lib/ where libcfitsio.a is placed, which comes with the HEASOFT installation). It is advisable to give the full path.
  8. Enabling the PGPLOT is optional.
  9. Choose the standard serial implementation, i.e. option "0".
  10. Accept the Position Independent Compilation.
  11. Choosing a shared/dynamic library is optional.
  12. Choose option "0": exit.

Finally, execute: make.

Note: The other software packages provided in the external directory will be built automatically.

General steps

Go to directory:

 $ cd /<my eSASS path>/eSASS4EDR/autoconf 

to perform the configuration of the installation. This can be achieved by launching the configure script there.

There are two main libraries required by configure: Healpix and HEASOFT. In most cases you will have a "default" HEASOFT installation, so you will have to provide the additional argument --with-headas=/path/to/heasoft/, for example:

 $ ./configure --with-healpix=/<my eSASS path>/external/Healpix_3.50 --with-headas=$HEADAS 

The Healpix option requires the absolute path.

You should be notified if you are missing crucial libraries on your system, such as GSL. You can now either specify to compile these libraries or install them on your own (for example, --with-gsl=system). In general eSASS ships with the source code for missing libraries except for HEASOFT. To avoid issues with automake versions it is recommended to first execute autoreconf. Moreover, on some systems configure will report executing aclocal before you run configure again.

Thus a more complex setup can look like this:

 $ autoreconf -i
 $ aclocal
 $ ./configure --with-caldb=yes --with-healpix=/<my eSASS path>/external/Healpix_3.50 \
   --with-headas=$HEADAS --with-gsl=compile --with-fftw=compile --with-lapack=compile

Continue the eSASS build by executing:

 $ make
 $ make install 

If you do not get any error message, congratulations! Your eSASS build should now be complete.

Finally, run the command

 $ make clean

to optionally remove files that are no longer needed after the completion of the build.

To enable the eSASS environment, execute the following command (either sh or csh version):

 $ source /<my eSASS path>/eSASS4EDR/bin/esass-init.[c]sh 

2.3 Patching individual eSASS tasks

Available task patches will be announced. Make sure your eSASS task archive is current by executing the script as described under Downloading. Then go to directory $SASS_ROOT/erosita/task/ and execute the following command:

 $ tar -xzf $SW_EXPARCH/<task>_<n.m>.tgz 

where <task> and <n.m> are the task name and version you want to update to. Then, go to the directory /<my eSASS path>/eSASS4EDR/build/ and execute:

 $ make clean 

Finally, go to /<my eSASS path>/eSASS4EDR/autoconf and execute:

 $ make
 $ make install 

You can also downgrade to a previous task version in the same way.

2.4 Troubleshooting

If the execution of the configure command for eSASS ends with the message:

 checking for library containing hpsharp_execute... no
 configure: error:  healpix not found 

Check that you have compiled Healpix without OMP support meaning you choose the answer 0 when asked for

 Do you want to use :
  0) the standard serial implementation ?
  1) the parallel implementation  

One can check if Healpix was compiled using OMP support by executing

 $ grep -n openmp Makefile 

If the output looks like

 Makefile:30:F90_FFLAGS  = -O3 -I$(F90_INCDIR) -DGFORTRAN -fno-second-underscore -fopenmp -fPIC
 Makefile:32:F90_CFLAGS  = -O3 -std=c99 -DgFortran -fopenmp -fPIC 

it means that Healpix was compiled with OMP support. Therefore, Healpix should be re-configured before proceeding.

3 Using eSASS on macOS, Windows and other Linux distributions

3.1 Introduction

Users with macOS, Windows and Linux distributions different from Ubuntu can use Docker to run eSASS on their computers. Containerization systems like Docker are meant as a way to distribute applications and their dependencies in a stable, lightweight way. For our usage here think of it as a small virtual machine that comes with eSASS and HEASoft pre-installed.

To start an eSASS container you need to install a Docker client and get it running in your machine:

Please note that a Docker client should not be simply be installed on servers with multiple users as that would introduce the possibility to circumvent file permissions on that machine. If this setup is unavoidable please consider setting up the client to run in Rootless mode.

3.2 The eSASS Docker containers

There are two Docker containers based on the eSASS4EDR installation available in the Docker Hub eROSITA repositories:

Both Docker containers are configured to use the CALDB from /home/idies/caldb. The environment variable CALDB is set to $CALDB=/home/idies/caldb and for esass-minimal it is expected that the external CALDB gets mounted there.

The eSASS software in the containers comes pre-compiled, but they also contain the source code of the eSASS software and of all its tasks. When launching the containers, the esass-init.[c]sh script is already launched and the programs can immediately be used. The binaries are located in:


The sources of the tasks are located in:


All software was built against the HEASoft installation in /opt/heasoft.

Downloading and launching the Docker containers

With the Docker client running you should be able to start a container running the full esass image like so:

 $ docker run -it --rm erosita/esass:latest /bin/bash 

or the minimal version where the CALDB directory is mounted from /path/to/caldb on the host machine:

 $ docker run --volume /path/to/caldb:/home/idies/caldb -it --rm erosita/esass-minimal:latest /bin/bash 

Note: The first execution of a Docker run command should start downloading the Docker image onto disk and it will take some minutes. The next executions of a Docker run on a previously downloaded image will be faster.

For an in-depth description of the command-line arguments used in the calls above you can refer to the reference manual online, but in short -it starts the container in an interactive session, --rm removes the container after execution and -v or --volume makes host machine directories accessible inside the container. The call to Bash, in the end, is the command that gets executed in the container, so together with -it, it will dump you in a shell inside the running container. One can of course specify other commands here such as direct calls to eSASS commands or scripts to execute.

In case the run command does not start the download automatically, the Docker image can be fetched manually with pull:

 $ docker pull erosita/esass:latest

This is also the command to use when a new eSASS user release comes out. The pull command will update the locally stored image from the registry.

3.3 Working with the Docker container

Just like a virtual machine, a Docker container behaves a lot like a remote Linux machine from the perspective of the host computer, and a bit of effort needs to be spent to make it convenient to work in this setup. There are also a number of caveats one needs to be aware of:

Containers are short-lived

The docker run commands above will start a container that only exists until one exits the shell again - with the next initialisation one gets a completely fresh copy. This means that any files which get written inside a container disappear with it. While it is possible to keep a container running and connect to it, it is still advisable to keep your data and programs outside of it. The easiest way to accomplish that is to use the -v / --volume option as above. The option can be used several times to mount many different directories.

Containers are (somewhat) static

An extension of the point above, the software installed inside it resets itself with each new container. So while it is possible to install missing python modules or install a program locally they would be gone the next time. There are a number of ways around this problem:

Getting GUIs to work

In order for programs running inside the Docker container to display graphical user interfaces on the X-window system of the host machine the $DISPLAY variable needs to get set inside the container and connections have to be allowed on the host machine:

 $ xhost +   # allow access to xhost from localhost being added to access control list
 $ docker run -ti --rm -e DISPLAY=host.docker.internal:0 erosita/esass:latest /bin/bash

If all goes well programs like fv will work as expected now. Unfortunately, the details can vary a bit depending of the operating system and setup of the host machine. The above was tested on macOS.

Memory settings

It can be that the default memory and CPU settings inside the client after installing, may be a bit low to work on the data. If this is the case, when running an eSASS task the user might get the following error:

 died with <Signals.SIGKILL: 9 >.

The most probable cause is the lack of memory in the Docker. The solution is to increase the memory allowed to the Docker client. To do this, go to the Docker engine Dashboard.

Various information

4 Support