ipac/firefly repository overview

⁠Firefly is IPAC's Advanced Astronomy WEB UI Framework. It is for building a web-based Front end to access science archives. It provides sophisticated interactive data visualization capabilities.

• GitHub: Firefly on GitHub⁠, Release Notes⁠

⁠Recent tags

• latest- Always set to the latest release
• 2026.3 - Always set to latest 2026.3
• 2026.3.0 - Sept 25, 2026 release
• 2026.2 - Always set to latest 2026.2
• 2026.2.1 - Aug 4, 2026 release
• 2026.1 - Always set to latest 2026.1
• 2026.1.5 - June 23, 2026 release
• 2026.1.4 - June 17, 2026 release
• 2025.5.4 - Feb 3, 2026 release
• 2025.5 - Always set to latest 2025.5
• nightly - The nightly build - unstable, but good for testing

⁠EXAMPLES

• -e : Define environment variable in the container
• -m : (or --memory=) The maximum amount of memory the container can use
• -p : Map a local port to a the container port (8080 is required)
• -v : Map a local directory to the container directory
• --rm : Remove the image after the run (recommended)

These examples use the tag name 'latest', you can use any tag name available, for example- 'release-2019.2.1'

⁠Very Simple - try this one first

• docker run -p 80:8080 -m 4g --rm ipac/firefly:latest
• start firefly with - http://localhost/firefly/⁠

⁠More advanced

• Background:

  • docker run -d -p 80:8080 --memory=8g --rm ipac/firefly:latest
  • start firefly with - http://localhost/firefly/⁠

• Map a directory for direct file reading:

  • docker run -p 80:8080 -v /local/data:/external --memory=8g --rm ipac/firefly:latest
  • start firefly with - http://localhost/firefly/⁠

• Write to logging directory outside of docker image:

  • docker run -p 80:8080 -v /local/myLogDir:/firefly/logs --memory=8g --rm ipac/firefly:latest
  • start firefly with - http://localhost/firefly/⁠

• View log file:

  • When running firefly interactively, logs will be echoed to the terminal. If you run firefly in detached mode(background), name the container so it can be used with docker logs to fetch the logs.
  • docker run --name test -d -p 80:8080 --memory=8g --rm ipac/firefly:latest
  • docker logs -f test
  • start firefly with - http://localhost/firefly/⁠

• Debugging:

docker run -p 8055:8080 -p 5050:5050 --memory=4g -e "ADMIN_PASSWORD=myPassword" -e DEBUG="TRUE" --rm --name firefly ipac/firefly:latest

• start firefly with - http://localhost:8055/firefly/⁠

• Production like:

docker run -p 8055:8080 -p --memory=30g -e "ADMIN_PASSWORD=myPassword" -e DEBUG="FALSE" --name productionServer ipac/firefly:latest

• start firefly with - http://localhost:8055/firefly/⁠

• Production like, multiple tomcats, using a shared work directory:

docker run -p 8055:8080 -p --memory=30g -e "ADMIN_PASSWORD=myPassword" -v /local/shared/work/area:/firefly/shared-workarea --name productionServer ipac/firefly:latest

• start firefly with - http://localhost:8055/firefly/⁠

⁠Environment Variables:

   - Description                      Name                          Value
  -  Admin username                   ADMIN_USER                    ${ADMIN_USER}
  -  Admin password                   ADMIN_PASSWORD                ${ADMIN_PASSWORD}
  -  Additional data path             VISUALIZE_FITS_SEARCH_PATH    ${VISUALIZE_FITS_SEARCH_PATH}
  - Clean internal(eg- 720m, 5h, 3d) CLEANUP_INTERVAL              ${CLEANUP_INTERVAL}
  - Base URL.  Default to /          baseURL                       ${baseURL:-/}

⁠Advanced environment variables:

  - Run tomcat with debug            DEBUG                         ${DEBUG}
  - Extra firefly properties(*)      PROPS                         ${PROPS}
  - Redis host                       PROPS_redis__host             ${PROPS_redis__host}
  - SSO host                         PROPS_sso__req__auth__hosts   ${PROPS_sso__req__auth__hosts}
  - firefly.options (JSON string)    PROPS_FIREFLY_OPTIONS         ${PROPS_FIREFLY_OPTIONS}

(*) key=value pairs separated by spaces

⁠Ports:

    8080 - http
    5050 - debug

⁠Volume Mount Points:

/firefly/logs             : logs directory
/firefly/workarea         : work area for temporary files
/firefly/shared-workarea  : work area for files that are shared between multiple instances of the application
/external                 : default external data directory visible to Firefly

Less used: /firefly/config : used to override application properties /firefly/logs/statistics : directory for statistics logs /firefly/alerts : alerts monitor will watch this directory for application alerts

⁠Command line options:

    --help  : show help message, examples, stop
    --debug : start in debug mode

⁠Customize

To fine tune the configuration you have to replace the launch page. Replacing the launch page - index.html or slate.html with your own with different configurations

• first extract and prepare you file from the example
  • create a empty directory to map to the container (example - mkdir /myDir)
  • docker run --rm -v /myDir:/local/www --name firefly ipac/firefly:latest --help
  • If the directory was empty, the container will place example html files into it.
  • Edit index.html to you liking (example - /myDir/index.html)
• docker run -p 80:8080 -v /myDir:local/www -m 4g --rm --name firefly ipac/firefly:latest
  • firefly maps this directory to "local"
  • start firefly with your alternative launch page- with http://localhost/local/⁠ or http://localhost/local/myFireflyPage.html⁠