search

sillsdev / languageforge-lexbox

Lexbox, SIL linguistic data hub
MIT License
7 stars 2 forks source link

readme

Staging workflow

Lexbox (formerly Language Depot)

Repo Structure

files related to a specific service should be in a folder named after the service. There are some exceptions:

Development

Prerequisites

Setup

Extra setup steps for Windows

If you're running Windows, you may need to add the following lines to your C:\Windows\system32\drivers\etc\hosts file:

127.0.0.1 resumable.localhost
127.0.0.1 hg.localhost
127.0.0.1 admin.localhost

On Linux, anything with a .localhost domain is automatically mapped to 127.0.0.1 so you don't need to edit your /etc/hosts file.

Kubernetes workflow

task up

The full app will be running at http://localhost after everything starts. There are some additional urls below to access specific parts of the system.

Local workflow

Prerequisites

Running the project

There are various ways to run the project. Here are a few suggestions:

For developing the .NET API

For developing the SvelteKit UI 1) In two seperate consoles:

The SvelteKit UI will be available at http://localhost:3000.

[!IMPORTANT] The SvelteKit UI is always available in k8s at http://localhost, but will not be reliable unless the entire project is started with task up.

For developing the .NET API and the SvelteKit UI

  • task infra-up starts all necessary infrastructure in k8s
  • task api:only starts the api locally
  • task ui:only starts the ui locally

If the k8s deployments are already running

Project urls

Seeded data

Once the database is created by the dotnet backend, it will also seed some data in the database. The following users are available, password for them all is just pass:

There will also be a single project, Sena 3. There will not be an hg repository however, see optional setup below if this is desired.

Architecture

flowchart TD
    Chorus --> lexbox-api

    subgraph lexbox pod 
        lexbox-api --> otel
    end
    lexbox-api --> hgweb
    lexbox-api --> hgresumable
    subgraph hg pod 
        hgweb
        hgresumable
    end
    hgweb --> hg[hg file system]
    hgresumable --> hg
    lexbox-api --> hg

    ui["ui (sveltekit)"] --> lexbox-api
    lexbox-api ---> db[(postgres)]

More info on the frontend and backend can be found in their respective READMEs:

Operational environment

Staging


flowchart LR
    Chorus(["Chorus (e.g. FLEx)"]) -- "https:(hg-staging|resumable-staging)" --- proxy
    Web -- https://staging.languagedepot.org --- proxy([ingress])

    proxy ---|http:5158/api or /hg| api([lexbox-api])
    proxy ---|http:3000| node([sveltekit])

    api -- postgres:5432 --- db([db])
    db -- volume-map:db-data --- data[//var/lib/postgresql/]

    api -- http:8088/hg --- hgweb([hgweb])
    hgweb -- /var/hg/repos --- repos
    api -- /hg-repos --- repos

    api -- http:80 --- hgresumable([hgresumable])
    hgresumable -- /var/vcs/public --- repos
    hgresumable -- hgresumable-cache --- cache[//var/cache/hgresume/]

    node <-->|http:5158/api & email| api

    api -- gRPC:4317 --- otel-collector([otel-collector])
    proxy ---|http:4318/traces| otel-collector
    node -- gRPC:4317 --- otel-collector

Monitoring & Analytics

This project is instrumented with OpenTelemetry (OTEL). The exported telemetry data can be viewed in Honeycomb.

For your local environment to send traces to Honeycomb, you will need to set the HONEYCOMB_API_KEY environment variable in the deployment/local-dev/local.env file. You can get the key from here.

Traces can be accessed directly with a URL like this: https://ui.honeycomb.io/sil-language-forge/environments/[test|staging|prod]/trace?trace_id=_TRACEID\. Yes, bookmark it!

In the application, a trace ID (aka "Error code") shown at the bottom of an error message can be Ctrl+clicked to navigate to the trace in Honeycomb.

Error example