Skip to content

soft-eng-practicum/AnalySim

Repository files navigation

Analysim

Analysim is a free online web platform enabling researchers to analyze and share data by providing interactive visualizations, and collaborate with others. The open platform is specialized for working with high-dimensional data sets such as those constructed via computational modeling. Analysim also allows you to run custom analysis on any type of data.

Installation

Clone the Analysim Repository from GitHub so that you have the project locally.

git clone https://github.com/soft-eng-practicum/AnalySim.git

Required software for development

Installing Angular package dependencies

After you have cloned the Analysim repository on your local machine, use the terminal to navigate to the AnalySim\src\Analysim.Web\ClientApp folder and run the following command.

npm install

Then navigate to AnalySim\src\Analysim.Web\ClientApp\src\assets\jupyter folder and run the following commands.

python -m pip install -r requirements.txt
jupyter-lite build --output-dir dist

Connecting to databases and other services

Analysim requires two databases to operate: one SQL database (PostgreSQL) for relational data and one Azure BlobStorage database for keeping uploaded user files. In addition, an Outlook account is needed for the email functionality. All of these services are accessed via authentication information stored in the appsettings.json and appsettings.Development.json files under the src/Analysim.Web folder. The structure of the files are as follows (XXX means redacted):

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "DBConnectionString": "User ID=XXX;Password=XXX;Server=XXX;Port=5432;Database=XXX;Integrated Security=true;Pooling=true;SSL Mode=Require;Trust Server Certificate=true",
    "AzureStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=XXX;AccountKey=XXX;EndpointSuffix=core.windows.net"
  },
  "EmailSettings": {
    "Server": "smtp-mail.outlook.com",
    "Port": 587,
    "SenderName": "no-reply-analysim",
    "SenderEmail": "XXX",
    "Username": "XXX",
    "Password": "XXX"
  },
  "JwtSettings": {
    "Issuer": "AnalySim",
    "Secret": "XXX",
    "ExpireTime": 60,
    "Audience": "https://www.analysim.tech/"
  },
  "UserQuota":  100000000,
  "registrationCodes": [ "123" ]
}

SQL database (also see Docker Compose option below)

If you don't have a SQL database yet, download and install PostgreSQL. See the example for installing on Ubuntu 22.04. Create a user account (tutorial) and replace the XXX values in the DBConnectionString above with the correct ones. Once you entered the correct details, you must be able to initialize and populate the database by using the Entity Framework migration tool by rinning the following command in the src/Analysim.Web folder:

dotnet ef database update

Azure Blob Storage

If you don't have an existing blob storage account, log into Microsoft Azure, and create a "Storage Account" with "Blob service" enabled. Then, select "Access Keys" on the left sidebar menu and copy one of the keys and insert both to replace the XXX in the AzureStorageConnectionString entry above. You will also need to insert your storage account name. In the same section on Azure, you can see the formatting for the correct Connection String as a guide. Blob storage falls under the free student services.

Outlook.com account

You can either use an existing Outlook account or create a new one and then fill in the XXX values under the section EmailSettings in the above file.

Running the project

In Visual Studio, open up the AnalySim.sln file. Click on the run to start the project. Once you have completed both steps, your project should be up and running!

Alternatively, without Visual Studio, you use .Net CLI from command line by first navigating into the src\Analysim.Web folder:

dotnet run --environment Development

(This will also automatically run Angular and a Swagger UI on port 5001)

Deploying

The overall process of deployment is explained in the tutorial video on deploying ASP.Net on Heroku using Docker.

Prerequisites

  1. Download Docker Desktop
  2. Download Heroku CLI
  3. Enable Docker Support

Publish .Net project and create Docker image

Note: Prepend sudo before each docker and heroku (except dotnet) command on Mac/Linux.

Using Docker Compose to compile and run the project by installing PostgreSQL in a container

You can run Analysim and the PostGreSQL in containers using Docker Compose. You have to follow a 2-step process to first apply the database migrations:

  1. Build and run the migrations container:
    docker compose -f docker-compose.yml -f docker-compose-db.yml build db-update
    docker compose -f docker-compose.yml -f docker-compose-db.yml run db-update
  2. Run the Analysim process with the database:
    docker compose build
    docker compose up

Using Docker manually to only run the project

  1. Publish Analysim.Web to the local folder (keep default location for folder), which can also be done on the command line:
    dotnet publish --configuration Release
  2. Create the Docker image by running the following in the base project folder (e.g. Analysim/) :
    docker build -t analysim-dev -f Dockerfile-run .
  3. Test image locally, by running it:
    docker run -it -p 127.0.0.1:80:80/tcp analysim-dev
    You can test by opening a browser to http://localhost:80 (not https).

Register and upload Docker image to Heroku

Note: Prepend sudo before each docker and heroku (except dotnet) command on Mac/Linux.

Run the following commands in terminal to update Heroku deployment (more info):

  1. Login to Heroku and container service (if using sudo, you may need to copy-paste into browser):
    heroku login
    heroku container:login
  2. Tag the image name on Heroku's container registry:
    docker tag analysim-dev registry.heroku.com/analysim-dev
    docker push registry.heroku.com/analysim-dev
  3. Change to the deploy/ folder and re-build image using Heroku CLI:
    cd deploy
    heroku container:push web -a analysim-dev --context-path=..
    heroku container:release web -a analysim-dev

Google Summer of Code application examples

Two successful application examples can be found under the doc/ folder.