previous

Welcome to SACRO Viewer

next

User Guide

Install#

SACRO Viewer is distributed as pre-built installers for Windows, Linux, and macOS. No additional dependencies or setup are required - the installers include everything needed to run the application.

System Requirements#

Windows

  • Windows 10 or later

  • Administrator privileges may be required for installation

Linux

  • Ubuntu 18.04 or later (or equivalent distribution)

  • 64-bit architecture (amd64)

macOS

  • macOS 10.14 (Mojave) or later

  • Intel or Apple Silicon processors supported

Windows Installation#

  1. Download the latest Windows release

  2. Unzip the downloaded file

  3. Run the included sacro 0.2.1.msi installer

  4. Follow the installation wizard prompts

  5. The application will launch automatically when installation completes

Note

Administrator privileges may be required to install the application. If you encounter permission issues, right-click the MSI file and select “Run as administrator”.

Linux Installation#

  1. Download the latest Linux release

  2. Unzip the downloaded file

  3. Install the included .deb package:

    sudo dpkg -i sacro_0.2.1_amd64.deb

  4. Launch the application from your applications menu or run sacro from the command line

macOS Installation#

  1. Download the latest macOS release

  2. Unzip the downloaded file

  3. Move Sacro.app to your Applications folder

  4. Right-click on the Sacro app icon and select “Open”

  5. macOS will display a security warning - click “Open” to proceed

  6. If the app is blocked, go to System Preferences → Security & Privacy and click “Open Anyway”

Warning

macOS may block the application because it’s not from an identified developer. This is normal for open-source applications. Follow the security steps above to allow the application to run.

Development Builds#

For testing the latest features, development builds are available:

Installing via pip#

You can also install SACRO Viewer as a Python package using pip:

pip install sacroviewer

To install a specific version:

pip install sacroviewer==0.2.1

To upgrade to the latest version:

pip install --upgrade sacroviewer

After installation, you can run the web application by starting the Django development server or deploying it as a standard Django application. For deployment options, refer to the Running the Web Application section below.

Caution

Development builds are automatically generated from the latest code and may contain bugs or incomplete features. Use stable releases for production environments.

Running the Web Application#

SACRO Viewer consists of two parts:

  1. A Django web app with vanilla JavaScript UI that renders a set of ACRO outputs for review

  2. An Electron app and installer that bundles the web app

The web app is designed to be used as a normally deployed website. The Electron app packages a pre-built version of this web app with a Chrome-based browser for desktop distribution.

System Requirements for Development#

General Requirements

  • Python 3.10

  • just command runner

  • Node.js v20

  • Git

Windows Specific Requirements

Windows requires additional setup:

Note

After installing all Windows requirements, please reboot your system.

Just commands will only work inside git-bash shell by default, as they assume bash.

Local Development Environment#

  1. Clone the repository:

    git clone https://github.com/AI-SDC/SACRO-Viewer.git
cd SACRO-Viewer

  2. Run the Django development server:

    just run

    This command will set up the Python virtual environment, install dependencies, and start the Django development server on http://localhost:8000

Development with Vite Live Reload#

If you are making changes to JavaScript, enable live reload:

  1. Set the environment variable:

    export DJANGO_VITE_DEV_MODE=true

  2. In a separate terminal, run the Vite development server:

    just assets-run

    The server will automatically refresh when you make changes to frontend assets.

Running the Electron App in Development#

To run the Electron app in development mode:

  1. First, start the Django development server:

    just run &

  2. Set the SACRO_URL environment variable:

    export SACRO_URL=http://127.0.0.1:8000

  3. Run the Electron app:

    just sacro-app/run

Testing#

Running Unit Tests#

Run the automated test suite:

just test <args>

Test Data#

The script data/test-nursery.py uses ACRO to generate outputs from a public test dataset. Test outputs are automatically regenerated as needed by the justfile for commands like just test or just run. Outputs are generated in the outputs/ directory.

To manually regenerate test data:

just test-outputs

To force removal of all test data and regenerate it:

just clean
just test-outputs

Testing the Electron App#

Semi-automated testing of the Electron app can be done locally using Cypress.

First, ensure a development server is running:

just run

Then open Cypress:

npm run cypress:open

To run Cypress in headless mode (useful for CI):

npm run cypress:run

Headless mode automatically produces a video on each run and provides screenshots of any errors.

Building the Application#

There are two stages to building the application for release: building the executable, then building the Windows installer (MSI).

Building the Python Web App#

To build the PyOxidizer binary:

just build

This creates a PyOxidizer binary of the Python application for your platform. The build process takes some time. The build executable and supporting files can be found in:

build/$ARCH/release/install/sacro

Building the Electron GUI App#

The sacro-app directory contains the Electron and packaging configuration and tooling.

To build the installer:

just sacro-app/build

This builds the Windows MSI installer, which can be found in sacro-app/dist.

Testing the Built Application#

To test the built application:

  1. Double-click the MSI file found in sacro-app/dist to install it

  2. The application will launch automatically

  3. You may need to click through various Windows dialogs to approve the installation

  4. Navigate to the outputs directory and choose results.json

  5. You should now see the outputs rendered in the app

  6. Click the Approve and Download button to test the download functionality

Technology Stack#

Backend * Django web framework with Python 3.10+ * PyOxidizer for bundling Python applications

Frontend * Vanilla JavaScript * Vite - modern build tool and development server * django-vite - Django integration for Vite

Frontend Asset Build Process

Vite compiles JavaScript files and outputs: * A manifest file * Compiled JavaScript files * Included assets (stylesheets, images, etc.)

Vite uses ES6 Module syntax for all JavaScript on the page. For legacy browser support, the Vite Legacy Plugin provides fallback support using the module/nomodule pattern.

Vite is configured to: * Build assets from assets/src * Output compiled assets to assets/dist * Django collects static files from assets/dist

Latest Development Builds#

Latest development builds are available via nightly.link:

Sample Data#

All download packages include sample data for testing the application:

  • Sample ACRO outputs in the outputs directory

  • Test files including CSV tables, images, and statistical results

  • Example metadata showing different ACRO status types (pass/fail/review)

To test the installation, launch SACRO Viewer and select the outputs directory from the downloaded package.

Troubleshooting#

Windows: “Windows protected your PC” message

This is normal for new applications. Click “More info” then “Run anyway” to proceed with installation.

macOS: “Cannot open because it is from an unidentified developer”

Go to System Preferences → Security & Privacy → General tab and click “Open Anyway” next to the blocked application message.

Linux: Permission denied errors

Ensure you have sudo privileges and the downloaded .deb file has execute permissions:

chmod +x sacro_0.2.1_amd64.deb
Application won’t start

Check that your system meets the minimum requirements listed above. On older systems, try running the application from the command line to see detailed error messages.

For additional support, please visit the GitHub Issues page.