Cohesive Auspice Server

A Spring Boot application that serves Auspice static content with proper URL routing support.

About

This server is designed to serve Auspice visualization files in the "Auspice way", meaning it correctly routes UUID-based paths to serve the appropriate index.html file while handling all other static content (HTML, CSS, JS, etc.) normally.

URL Routing

The server handles two types of Auspice-specific routes:

1. UUID pattern: /{uuid:[a-f0-9-]+}

   • Example: /b42a72fa-0123-4ff5-9c46-11961e9aa565 → serves index.html

2. UUID with dataset suffix: /{uuid:[a-f0-9-]+}_{dataset:[a-zA-Z0-9]+}

   • Example: /b42a72fa-0123-4ff5-9c46-11961e9aa565_myDataset → serves index.html

All other paths serve static content directly from the public directory.

Prerequisites

• Java 8 or higher
• Maven 3.x
• Built Auspice files (see Auspice documentation)

Installation

1. Clone this repository:

   git clone https://github.com/genpat-it/cohesive-auspice-server.git
   cd cohesive-auspice-server

2. Place your built Auspice files in:

   src/main/resources/public/
   

3. Build the WAR file:

   mvn clean package

   The WAR file will be generated at: target/auspice.war

Usage

Running locally

mvn spring-boot:run

The server will start on http://localhost:8080

Deploying as WAR

Deploy the generated auspice.war file to any servlet container (Tomcat, Jetty, etc.).

Configuration

The application uses Spring Boot's default configuration. You can customize settings in src/main/resources/application.yml.

CI/CD

This project includes a GitHub Action that automatically:

• Builds the WAR file on every push to main
• Runs on pull requests
• Uploads the WAR as a downloadable artifact
• Creates releases with attached WAR files when you push a version tag

Creating a release

git tag v1.0.0
git push origin v1.0.0

The WAR file will be automatically attached to the GitHub release.

Project Structure

auspice-server/
├── src/
│   └── main/
│       ├── java/
│       │   └── it/izs/bioinfo/auspice/
│       │       ├── Application.java         # Spring Boot main class
│       │       └── AuspiceController.java   # URL routing controller
│       └── resources/
│           ├── application.yml              # Configuration
│           └── public/                      # Place Auspice files here
│               └── error/
│                   ├── 404.html
│                   └── 500.html
├── .github/
│   └── workflows/
│       └── build.yml                        # GitHub Actions workflow
├── pom.xml                                  # Maven configuration
├── LICENSE                                  # MIT License
└── README.md

About Auspice

Auspice is an open-source interactive tool for visualizing phylogenomic data, developed by the Nextstrain team. This server application provides a convenient way to deploy and serve Auspice visualizations with proper URL routing support.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Auspice by Nextstrain team
• Spring Boot

Contact

For questions or support, please contact: cohesive@izs.it