Skip to main content

Setup

Prerequisites​

Before you begin, ensure you have the following installed on your system:

Song-Server Development Setup​

This guide will walk you through setting up a complete development environment, including Song and its complementary services.

Setting up supporting services​

We'll use our Conductor service, a flexible Docker Compose setup, to spin up Song's complementary services.

  1. Clone the Conductor repository and move into its directory:

    git clone https://github.com/overture-stack/conductor.git
    cd conductor

  2. Run the appropriate start command for your operating system:

    Operating SystemCommand
    Unix/macOSmake SongDev
    Windows./make.bat SongDev
    Click here for a detailed breakdown

    This command will set up all complementary services for Song development as follows:

    SongDev

    ServicePortDescriptionPurpose in Song Development
    Conductor9204Orchestrates deployments and environment setupsManages the overall development environment
    Keycloak-db-Database for Keycloak (no exposed port)Stores Keycloak data for authentication
    Keycloak8180Authorization and authentication serviceProvides OAuth2 authentication for Score
    Song-db5433Database for SongStores metadata managed by Song
    Score8087File Transfer serviceHandles file uploads, downloads, and storage operation
    Minio9000Object storage providerSimulates S3-compatible storage for Score
    • Ensure these ports are free on your system before starting the environment.
    • You may need to adjust the ports in the docker-compose.yml file if you have conflicts with existing services.

    For more information, see our Conductor documentation linked here

Running the Development Server​

  1. Clone Song and move into its directory:

    git clone https://github.com/overture-stack/song.git
    cd song

  2. Build the application locally:

    ./mvnw clean install -DskipTests
    Click here for an explaination of command above
    • ./mvnw: This is the Maven wrapper script, which ensures you're using the correct version of Maven.
    • clean: This removes any previously compiled files.
    • install: This compiles the project, runs tests, and installs the package into your local Maven repository.
    • -DskipTests: This flag skips running tests during the build process to speed things up.
    tip

    Ensure you are running JDK11. To check, you can run java --version. You should see something similar to the following:

    openjdk version "11.0.18" 2023-01-17 LTS
    OpenJDK Runtime Environment Corretto-11.0.18.10.1 (build 11.0.18+10-LTS)
    OpenJDK 64-Bit Server VM Corretto-11.0.18.10.1 (build 11.0.18+10-LTS, mixed mode)

  3. Start the Song Server:

    ./mvnw spring-boot:run -Dspring-boot.run.profiles=default,dev,secure -pl song-server
    info

    If you are looking to configure Song for your specific environment, the Song-server configuration file can be found here. A summary of the available Spring profiles is provided below:

    Click here for a summary of the Song-server spring profiles

    Song Profiles

    ProfileDescription
    defaultRequired to load common configurations
    secureRequired to load security configuration
    dev(Optional) Facilitates development default configuration
    prod(Optional) Loads production-specific configurations
    kafka(Optional) Enables Kafka integration
    score-client-cred(Optional) Configures SCORE client credentials
    testUsed for testing purposes
    async-testUsed for asynchronous testing
    fastTestUsed for fast testing with reduced timeouts

Verification​

After installing and configuring Song, verify that the system is functioning correctly:

  1. Check Server Health

    curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/isAlive" -H "accept: */*"
    • Expected result: Status code 200
    • Troubleshooting:
      • Ensure Song server is running
      • Check you're using the correct port (default is 8080)
      • Verify no firewall issues are blocking the connection

  2. Check the Swagger UI

    • Navigate to http://localhost:8080/swagger-ui.html in a web browser
    • Expected result: Swagger UI page with a list of available API endpoints
    • Troubleshooting:
      • Check browser console for error messages
      • Verify you're using the correct URL

  3. Test GET Analysis Endpoint

    • Using Swagger UI:
      1. Locate the GetAnalysesForStudy endpoint in the Analysis section: GET /studies/{studyId}/analysis/paginated
      2. Click to expand and select "Try it out"
      3. Set parameters:
        • analysisStates: PUBLISHED
        • studyId: demo
      4. Click "Execute"
    • Alternatively, use curl: 
      curl -X GET "http://localhost:8080/studies/demo/analysis?analysisStates=PUBLISHED" -H "accept: */*"
    • Expected result: JSON response containing analysis data for the demo study
Need Help?

If you encounter any issues or have questions about our API, please don't hesitate to reach out through our relevant community support channels.

Song-Client Setup​

The song-client is a CLI tool used for communicating with a song-server. For ease of deployment it can be run using Docker. The client can be configured through environment variables, which take precedence over the application.yml config.

docker run -d --name song-client \
   -e CLIENT_ACCESS_TOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528 \
   -e CLIENT_STUDY_ID=demo \
   -e CLIENT_SERVER_URL=http://localhost:8080 \
   --network="host" \
   --platform="linux/amd64" \
   --mount type=bind,source=${pwd},target=/output \
ghcr.io/overture-stack/song-client:5.1.1 \
Click here for an explaination of command above
  • -e CLIENT_ACCESS_TOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528 sets up the song-client with a pre-configured system-wide access token that works with the conductor service setup.
  • -e CLIENT_STUDY_ID=demo the quickstart is pre-configured with a Study ID named demo, we supply the Study ID value to the song-client on start-up.
  • -e CLIENT_SERVER_URL=http://localhost:8080 is the url for the Song server which the Song-Client will interact with.
  • --network="host" Uses the host network stack inside the container, bypassing the usual network isolation. This means the container shares the network namespace with the host machine.
  • --platform="linux/amd64" Specifies the platform the container should emulate. In this case, it's set to linux/amd64, indicating the container is intended to run on a Linux system with an AMD64 architecture.
  • --mount type=bind,source={pwd},target=/output mounts the directory and its contents (volume) from the host machine to the container. In this case, it binds the present working directory from the host to /output inside the container. Any changes made to the files in this directory will be reflected in both locations.
warning

This guide is meant to demonstrate the configuration and usage of Song for development purposes and is not intended for production. If you ignore this warning and use this in any public or production environment, please remember to use Spring profiles accordingly. For production do not use dev profile.