Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

73 migrate docs here #75

Closed
wants to merge 5 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,35 @@
kubeconfig
uscd.yaml
# Created by https://www.toptal.com/developers/gitignore/api/osx
# Edit at https://www.toptal.com/developers/gitignore?templates=osx

### OSX ###
# General
.DS_Store
.AppleDouble
.LSOverride

# Icon must end with two \r
Icon

# Thumbnails
._*

# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk

# End of https://www.toptal.com/developers/gitignore/api/osx

Expand Down
19 changes: 19 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Required
version: 2

# Build documentation with MkDocs
mkdocs:
configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

# Set the OS, Python version and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.12"
# You can also specify other tool versions:
# nodejs: "20"
# rust: "1.70"
# golang: "1.20"
2 changes: 1 addition & 1 deletion charts/mint/Chart.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ type: application
# This is the chart version. This version number should be incremented each time you make changes
# to the chart and its templates, including the app version.
# Versions are expected to follow Semantic Versioning (https://semver.org/)
version: 3.4.0
version: 3.4.1
# This is the version number of the application being deployed. This version number should be
# incremented each time you make changes to the application. Versions are not expected to
# follow Semantic Versioning. They should reflect the version the application is using.
Expand Down
2 changes: 1 addition & 1 deletion charts/mint/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MINT

![Version: 3.4.0](https://img.shields.io/badge/Version-3.4.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 1.16.3](https://img.shields.io/badge/AppVersion-1.16.3-informational?style=flat-square)
![Version: 3.4.1](https://img.shields.io/badge/Version-3.4.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 1.16.3](https://img.shields.io/badge/AppVersion-1.16.3-informational?style=flat-square)

A Helm chart for MINT

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
The Model Catalog Endpoint is a [SPARQL](https://www.w3.org/TR/sparql11-overview/) endpoint that provides access to the model catalog data. The Model Catalog Endpoint is implemented using [Apache Jena Fuseki](https://jena.apache.org/documentation/fuseki2/). The Model Catalog Endpoint is used by the MINT platform to store and retrieve model metadata.

The Model Catalog Endpoint is password protected. The default username and password are `admin` and `CHANGEME`, respectively. You can change the username and password by editing the `values.yaml` file in the `mint` directory. The `values.yaml` file contains the following sections:

The default url is [http://endpoint.models.mint.local](http://endpoint.models.mint.local)

```yaml
secrets:
database:
model_catalog_endpoint:
# -- Username for Model Catalog Apache Jena Fuseki database
username: admin
# -- Password for Model Catalog Apache Jena Fuseki database
password: CHANGEME
```

### Initial Data

Helm charts are configured to populate the database with initial data. You can configure the initial data by editing the `values.yaml` file in the `mint` directory. The `values.yaml` file contains the following sections:

!!! Note

The initial data file must be in the [Turtle](https://www.w3.org/TR/turtle/) format.
The process of loading the initial data is done only once when the Model Catalog Endpoint is installed.

```yaml
components:
model_catalog_endpoint:
environment:
seeds_url: https://raw.githubusercontent.com/mintproject/model-catalog-endpoint/main/data/wifire-2023-09-22.trig
```

The `seeds_url` key specifies the URL of the initial data. You can change the URL to point to a different initial data file. The initial data file must be in the [Turtle](https://www.w3.org/TR/turtle/) format.
54 changes: 54 additions & 0 deletions docs/admin-guide/catalog-configuration/region-configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
Helm charts are configured to populate the database with initial data containing multiple regions. You can remove the regions by querying the database and deleting the regions. The following sections describe how to query the database and delete the regions.

## Open the database

To open the database, use the following command:

```bash
$ kubectl exec -ti $(kubectl get pod -l app=mint-hasura -o jsonpath='{.items[0].metadata.name}') -c hasura-db -- sh
```

## Query the database

To query the database, use the following command:

```bash
$ psql -U postgres -d hasura
```

The following SQL query will remove all region geometry that are not California:

```sql
SELECT
rg.region_id
FROM
region
INNER JOIN
region_geometry rg
ON
region.id = rg.region_id
WHERE
region.parent_region_id IS NULL
AND region.parent_region_id != 'california';
```

```sql
DELETE FROM region_geometry
USING region
WHERE region_geometry.region_id = region.id
AND region.parent_region_id != 'california';
```

The following SQL query will remove all region geometry that are not California and are not a child of California:

```sql
DELETE FROM region
WHERE region.parent_region_id != 'california' AND region.id != 'california';
```

Delete all region that the id is not `california` and the `parent_region_id` is `NULL`:

```sql
DELETE FROM region
WHERE region.parent_region_id IS NULL AND region.id != 'california';
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
MINT uses [hasura](https://hasura.io/) to store the task, problem, execution and other metadata.

The Hasura database is password protected. The default secret is `CHANGEME` can change the username and password by editing the `values.yaml` file in the `mint` directory. The `values.yaml` file contains the following sections:

The default url is [http://graphql.mint.local](http://graphql.mint.local)

```yml
secrets:
hasura:
# -- Admin secret for Hasura used to access the console
admin_secret: CHANGEME
```

## Initial Data

Helm charts are configured to populate the database with initial data.

!!! Note

The process of loading the initial data is done only once when the Hasura is installed.

To delete existing regions, please go to the [Region Configuration](region-configuration.md) page.
34 changes: 34 additions & 0 deletions docs/admin-guide/ckan-configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
MINT supports CKAN as a data catalog. CKAN is a powerful data management system that makes data accessible by providing tools to streamline publishing, sharing, finding, and using data. CKAN is aimed at data publishers (national and regional governments, companies, and organizations) wanting to make their data open and available.

## Features

MINT CKAN provides the following features:

- Query and search for datasets
- View dataset metadata
- Publish datasets and resources from the execution of a workflow

## Configuration

The CKAN configuration is stored in the `values.yaml` file in the `mint` directory. The `values.yaml` file contains the following sections:

```yaml
external_services:
ckan:
# -- Enable or disable CKAN service
enabled: true
# -- CKAN url
url: "http://localhost:5000"
# -- CKAN service type
type: "CKAN"
extra:
# -- Owner organization ID for CKAN service
owner_organization_id: ""
# -- Owner provenance ID for CKAN service
owner_provenance_id: ""``
secrets:
external_services:
ckan:
# -- API key for CKAN service. Used by Ensemble Manager to upload data
api_key: CHANGEME
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Kubernetes

MINT can run models as job on Kubernetes clusters. This guide explains how to set up a Kubernetes cluster for MINT execution.

Configure the Kubernetes cluster in the `values.yaml`.

```yaml
external_services:
kubernetes:
# -- Enable or disable Kubernetes service to run jobs used by Ensemble Manager
enabled: true
# -- Kubernetes namespace
namespace: 'default'
# -- Job CPU limit
cpu_limit: '256m'
# -- Job memory limit
memory_limit: '512Mi'
# -- Toggle for node affinity. The job will be scheduled on the same node as the Ensemble Manager
node_affinity: true
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Tapis

MINT can run models as job on Tapis clusters. The models should be existing Tapis apps. This guide explains how to set up a Tapis cluster for MINT execution.

TODO: Add instructions for setting up Tapis cluster for MINT execution.
7 changes: 7 additions & 0 deletions docs/admin-guide/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Overview

This guide is for Administrators who need to set up a new [MINT](https://mint.isi.edu) installation.

!!! Note
Please make sure you have completed the User guide before you start.

90 changes: 90 additions & 0 deletions docs/admin-guide/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Install

MINT can be easily deployed on large Kubernetes clusters using Helm. Useful for production instances.

## Pre-requisites

- A Kubernetes `v1.16.3` cluster or later.
- Helm `v3.2.x` or later.

If you don't have a Kubernetes cluster and you want to test MINT, we **strongly** recommend to use [Microk8s](https://microk8s.io/) to create a local cluster on your machine. Follow the instructions in the [MINT](https://github.com/mintproject/mint/?tab=readme-ov-file#mint) to install Microk8s on your machine.

## Install MINT

Add the MINT Helm repository:

```bash
$ helm repo add mint https://mintproject.github.io/mint
```

Update the Helm repository:

```bash
$ helm repo update
```

Install MINT:

```bash
$ helm install mint mint/mint --namespace mint --create-namespace
```

If you using MacOS Silicon, you need to install the `arm64` version of the postgresql database.

**WARNING:** The arm64 image has not been tested and may not work as expected. Please use it at your own risk.

```bash
$ helm install mint mint/mint --namespace mint --create-namespace --set arm_support=true
```

Helm will returns the URL to access the MINT services. You can use the following command to get the URL:

```txt
The MINT system has been installed!

Please remember to edit your `/etc/hosts/`

After that, you can access to the MINT services


http://mint.local
http://ensemble-manager.mint.local
http://cromo.mint.local
http://mic.mint.local
http://datacatalog.mint.local
```

If you are using microk8s on a VM (macOS or windows) need to get the IP address of the VM to access the MINT services. You can use the following command to get the IP address of the VM:

```bash
$ kubectl get node -o json | jq '.items[].status.addresses[] | select(.type=="InternalIP") | .address'
10.211.59.16
```

Then, edit the `/etc/hosts` file and add the following lines:

```bash
$ sudo vim /etc/hosts
```

Add the following lines (replace the IP address with the IP address of the VM):

```text
10.211.59.16 mint.local
10.211.59.16 cromo.mint.local
10.211.59.16 mic.mint.local
10.211.59.16 api.mic.mint.local
10.211.59.16 datacatalog.mint.local
10.211.59.16 endpoint.models.mint.local
10.211.59.16 graphql.mint.local
10.211.59.16 models.mint.local
10.211.59.16 api.models.mint.local
10.211.59.16 endpoint.models.mint.local
```

Got to the URL returned by Helm to access the MINT services.

The default username and password are:

- Username: `[email protected]`
- Password: `mint123!`
6 changes: 6 additions & 0 deletions docs/assets/extra.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.md-grid {
max-width: 80rem;
}
.md-nav__item--active {
font-weight: bold;
}
Loading