Package Consumption¶
이 문서는 Nexus에 publish된 Tirosh package를 다른 project에서 설치하고 사용하는 방법을 설명합니다.
처음 보는 개발자는 source repo를 clone하지 않아도 이 문서만으로 package consume 흐름을 따라갈 수 있어야 합니다. Nexus repository 운영 기준은 Nexus가 담당하고, 이 문서는 consumer가 알아야 할 registry 주소, 인증 방법, 설치 명령, import 예시에 집중합니다.
1. 사용 전 필요한 정보¶
1-1. 필요한 권한¶
Package를 설치하려면 Nexus read 권한이 있는 계정이 필요합니다.
| 필요 정보 | 설명 |
|---|---|
NEXUS_USERNAME |
Nexus package read 권한이 있는 사용자 또는 service account입니다. |
NEXUS_PASSWORD |
해당 계정의 password 또는 token입니다. |
| Repository URL | package ecosystem별 download endpoint입니다. |
| Package version | 설치할 release version입니다. 예시는 0.1.0을 사용합니다. |
Credential은 shell env, CI secret, password manager를 통해 전달합니다. Password나 token을 package.json, pyproject.toml, Cargo.toml, go.mod, 문서, commit에 남기지 않습니다.
1-2. Package catalog¶
이 guide repo에서 consumer가 직접 설치할 수 있는 reusable package는 아래와 같습니다.
| Ecosystem | Package | 역할 |
|---|---|---|
| npm / pnpm | @tirosh/patient-monitor-ui-core |
Monitoring API response를 frontend ViewModel로 변환합니다. |
| npm / pnpm | @tirosh/patient-monitor-react-components |
Patient monitoring React component와 hook을 제공합니다. |
| Python / uv | patient-risk-python-core |
Patient risk domain model, usecase, port를 제공합니다. |
| Python / uv | python-persistence |
Python storage adapter가 공유하는 persistence 설정을 제공합니다. |
| Python / uv | patient-signal-python-rust |
Rust signal preprocessing Python binding을 제공합니다. |
| Rust / Cargo | patient-signal-rust-core |
Board-independent signal preprocessing domain logic을 제공합니다. |
| Go | github.com/tirosh-chain/tirosh-dev-guide/source-repo/packages/patient-risk-go-core |
Go 기반 risk assessment domain rule을 제공합니다. |
| Conan / C | patient-signal-c-core |
C firmware와 native consumer가 공유하는 signal rule library입니다. |
1-3. Repository endpoint¶
Consumer는 package ecosystem에 맞는 download endpoint를 사용합니다. npm, PyPI, Conan은 group endpoint를 우선 사용하고, Cargo는 crates.io proxy와 Tirosh crate registry를 함께 설정합니다. Raw firmware artifact는 dependency manager가 없으므로 raw hosted URL을 직접 사용합니다.
Group endpoint는 사내 package만 바라보는 주소가 아닙니다. Nexus group은 Tirosh hosted repository와 공식 upstream registry proxy를 묶어서, consumer가 하나의 URL로 사내 package와 public dependency를 함께 resolve하게 합니다.
| Repository role | 의미 | 예시 |
|---|---|---|
| Proxy | 공식 package registry를 cache합니다. | npmjs, PyPI, crates.io, Go proxy, Conan Center |
| Hosted | Tirosh가 만든 package를 publish하는 저장소입니다. | npm-guide-hosted, pypi-guide-hosted |
| Group | proxy와 hosted를 하나의 download endpoint로 묶습니다. | npm, pypi, conan |
이 guide repo의 artifact는 guide가 붙은 hosted repository에 publish됩니다. 일반 사내 제품 package는 같은 naming rule에서 guide- 또는 -guide 부분이 빠진 repository를 사용합니다.
| Ecosystem | Consumer download endpoint | 비고 |
|---|---|---|
| npm / pnpm | https://nexus.internal.tirosh.ai/repository/npm/ |
|
| Python / uv | https://nexus.internal.tirosh.ai/repository/pypi/simple/ |
|
| Rust / Cargo proxy | sparse+https://nexus.internal.tirosh.ai/repository/cargo/ |
crates.io dependency cache입니다. |
| Go | https://nexus.internal.tirosh.ai/repository/go/ |
|
| Conan / C | https://nexus.internal.tirosh.ai/repository/conan/ |
|
| Firmware raw | https://nexus.internal.tirosh.ai/repository/raw-embedded-guide-hosted |
Guide firmware artifact 전용입니다. 일반 사내 firmware는 raw-embedded-hosted를 사용합니다. |
Guide package를 직접 가리켜야 하는 hosted endpoint는 아래와 같습니다.
| Ecosystem | Guide hosted endpoint | 일반 사내 hosted endpoint |
|---|---|---|
| npm publish target | https://nexus.internal.tirosh.ai/repository/npm-guide-hosted/ |
https://nexus.internal.tirosh.ai/repository/npm-hosted/ |
| PyPI publish target | https://nexus.internal.tirosh.ai/repository/pypi-guide-hosted/ |
https://nexus.internal.tirosh.ai/repository/pypi-hosted/ |
| Cargo Tirosh crate registry | sparse+https://nexus.internal.tirosh.ai/repository/cargo-guide-hosted/ |
sparse+https://nexus.internal.tirosh.ai/repository/cargo-hosted/ |
| Go module | hosted repository를 사용하지 않습니다. Git tag가 release source이고 Nexus Go repository가 proxy/cache합니다. | 동일합니다. |
| Conan publish target | https://nexus.internal.tirosh.ai/repository/conan-guide-hosted/ |
https://nexus.internal.tirosh.ai/repository/conan-hosted/ |
| Firmware raw hosted | https://nexus.internal.tirosh.ai/repository/raw-embedded-guide-hosted |
https://nexus.internal.tirosh.ai/repository/raw-embedded-hosted |
대부분의 consumer는 group endpoint만 알면 됩니다. Cargo처럼 dependency 선언에서 private registry 이름이 필요한 경우나 raw firmware처럼 group이 없는 경우에만 guide hosted endpoint를 명시합니다.
1-4. Release package 기준¶
기본 소비 대상은 release package입니다. main merge에서 dev container image는 자동 갱신될 수 있지만, package는 다른 project의 dependency resolver에 들어가기 때문에 release 전 snapshot을 기본 publish하지 않습니다.
| Channel | 소비 기준 |
|---|---|
| Release package | tag/release workflow가 publish한 고정 version을 사용합니다. |
| Dev package | 다른 repo가 release 전 package를 꼭 설치해야 할 때만 별도 dev repository나 dev channel을 둡니다. |
| Local source | 같은 workspace에서 개발할 때는 publish 없이 local workspace dependency로 검증합니다. |
설치하려는 version이 Nexus에 없다면 package 이름보다 먼저 release workflow에서 해당 version이 publish되었는지 확인합니다.
2. TypeScript / React Package¶
2-1. Registry 설정¶
TypeScript package는 npm compatible repository에서 설치합니다. Tirosh package는 @tirosh scope를 사용합니다.
npm login \
--registry=https://nexus.internal.tirosh.ai/repository/npm/ \
--scope=@tirosh
Login 후 project의 package manager가 @tirosh scope를 Nexus로 보도록 설정합니다.
pnpm config set @tirosh:registry https://nexus.internal.tirosh.ai/repository/npm/
CI나 자동화 환경에서는 repository secret으로 .npmrc를 생성합니다. Credential이 들어간 .npmrc는 commit하지 않습니다.
2-2. 설치¶
pnpm add @tirosh/patient-monitor-ui-core@0.1.0
pnpm add @tirosh/patient-monitor-react-components@0.1.0 react react-dom
patient-monitor-react-components는 React와 React DOM을 peer dependency로 둡니다. Consumer app은 app에서 쓰는 React version을 직접 관리합니다.
2-3. 사용 예시¶
@tirosh/patient-monitor-ui-core는 API response를 화면용 view model로 바꾸는 순수 TypeScript package입니다.
import {
createMonitoringSnapshotViewModel,
fetchMonitoringSnapshot
} from "@tirosh/patient-monitor-ui-core";
const liveViewModel = await fetchMonitoringSnapshot("https://api.example.internal");
const offlineViewModel = createMonitoringSnapshotViewModel(snapshotJson);
@tirosh/patient-monitor-react-components는 React component와 hook을 제공합니다.
import { createMonitoringSnapshotViewModel } from "@tirosh/patient-monitor-ui-core";
import { PatientMonitorDashboard } from "@tirosh/patient-monitor-react-components";
const initialSnapshot = createMonitoringSnapshotViewModel(snapshotJson);
export function Page() {
return (
<PatientMonitorDashboard
apiBaseUrl="https://api.example.internal"
initialSnapshot={initialSnapshot}
/>
);
}
2-4. 확인할 것¶
Install이 public npm으로 나가면 scope registry 설정을 확인합니다.
pnpm config get @tirosh:registry
3. Python Package¶
3-1. Registry 설정¶
Python package는 PyPI compatible repository에서 설치합니다. Consumer project가 uv를 사용한다면 pyproject.toml에 Tirosh PyPI index를 추가합니다.
[[tool.uv.index]]
name = "tirosh-pypi"
url = "https://nexus.internal.tirosh.ai/repository/pypi/simple/"
default = true
authenticate = "always"
Credential은 environment variable로 전달합니다.
export UV_INDEX_TIROSH_PYPI_USERNAME="$NEXUS_USERNAME"
export UV_INDEX_TIROSH_PYPI_PASSWORD="$NEXUS_PASSWORD"
3-2. 설치¶
uv add patient-risk-python-core==0.1.0
uv add python-persistence==0.1.0
uv add patient-signal-python-rust==0.1.0
pip을 직접 사용하는 project라면 index URL은 같게 두되, credential은 pip config나 CI secret으로 주입합니다.
python -m pip install \
--index-url https://nexus.internal.tirosh.ai/repository/pypi/simple/ \
patient-risk-python-core==0.1.0
3-3. 사용 예시¶
patient-risk-python-core는 domain model, usecase, port를 제공합니다.
from patient_risk_python_core import create_model_observation
observation = create_model_observation(
encounter_id="enc-001",
model_name="baseline",
risk_score=0.72,
horizon="24h",
)
assert observation.risk_score > 0
python-persistence는 storage adapter가 공유하는 persistence 설정과 readiness helper를 제공합니다.
from python_persistence import KeyBuilder, Keyspace
keyspace = Keyspace(prefix="patient-risk")
key = KeyBuilder(keyspace).key("dev", "encounter", "enc-001")
patient-signal-python-rust는 Rust 기반 signal preprocessing Python binding입니다.
import patient_signal_python_rust as signal_rust
capabilities = signal_rust.preprocessor_capabilities()
assert capabilities["engine"] == "rust"
3-4. 확인할 것¶
Python wheel은 platform tag의 영향을 받습니다. Linux container에서 사용할 package라면 Linux용 wheel이 publish되어 있어야 합니다. macOS에서 만든 wheel은 Linux pod에서 사용할 수 없습니다.
4. Rust Crate¶
4-1. Registry 설정¶
Rust crate는 Cargo compatible registry에서 설치합니다. Consumer project에 .cargo/config.toml을 추가합니다.
[source.crates-io]
replace-with = "tirosh-nexus-proxy"
[source.tirosh-nexus-proxy]
registry = "sparse+https://nexus.internal.tirosh.ai/repository/cargo/"
[registries.tirosh-nexus]
index = "sparse+https://nexus.internal.tirosh.ai/repository/cargo-guide-hosted/"
cargo-guide-hosted는 이 guide package 전용 registry입니다. 일반 사내 제품 crate를 소비하는 project라면 같은 위치에 cargo-hosted registry를 사용합니다.
Cargo credential은 developer machine이나 CI secret에서 관리합니다. Credential이 들어간 파일은 commit하지 않습니다.
4-2. 설치¶
Consumer crate의 Cargo.toml에 dependency를 추가합니다.
[dependencies]
patient-signal-rust-core = { version = "0.1.0", registry = "tirosh-nexus" }
4-3. 사용 예시¶
patient-signal-rust-core는 board-independent signal preprocessing domain logic을 제공합니다.
use patient_signal_rust_core::{present_signal_quality, SignalQuality};
let label = present_signal_quality(&SignalQuality::Good);
assert_eq!(label, "good");
4-4. 확인할 것¶
cargo build --locked가 registry 인증 문제로 실패하면 .cargo/config.toml의 registry URL과 Cargo credential 설정을 확인합니다.
5. Go Module¶
5-1. Registry 설정¶
Go module은 package 파일을 Nexus hosted repository에 upload하는 방식이 아닙니다. Go proxy가 Git module을 cache하고, consumer는 module path와 version tag를 기준으로 가져옵니다.
Go ecosystem의 de facto release source는 package archive upload가 아니라 VCS tag입니다. npm, PyPI, Cargo, Conan은 package artifact를 hosted repository에 publish하지만, Go는 Git repository의 semver tag를 기준으로 module zip을 만들고 proxy가 이를 cache합니다. 그래서 Go에는 go-hosted publish target을 두지 않습니다.
Shell에서 Nexus Go proxy를 지정합니다.
export GOPROXY=https://nexus.internal.tirosh.ai/repository/go/
export GONOSUMDB=github.com/tirosh-chain/*
Private GitHub repository를 경유해야 한다면 Git credential helper나 .netrc도 필요할 수 있습니다.
5-2. 설치¶
go get github.com/tirosh-chain/tirosh-dev-guide/source-repo/packages/patient-risk-go-core@v0.1.0
5-3. 사용 예시¶
Go package는 risk assessment domain rule을 제공합니다.
import riskdomain "github.com/tirosh-chain/tirosh-dev-guide/source-repo/packages/patient-risk-go-core/domain"
policy := riskdomain.DefaultRiskPolicy()
level := riskdomain.ClassifyRiskLevel(0.72, policy)
_ = level
5-4. 확인할 것¶
Go module은 submodule tag 규칙의 영향을 받습니다. packages/patient-risk-go-core module을 release하려면 해당 module path에 맞는 tag가 있어야 합니다.
6. C / Conan Package¶
6-1. Registry 설정¶
C package는 Conan remote에서 설치합니다. Consumer machine에 Tirosh Conan remote를 추가합니다.
conan remote add tirosh-conan https://nexus.internal.tirosh.ai/repository/conan/ --force
conan remote login tirosh-conan "$NEXUS_USERNAME" -p "$NEXUS_PASSWORD"
6-2. 설치¶
Consumer project의 conanfile.txt에 dependency를 추가합니다.
[requires]
patient-signal-c-core/0.1.0
[generators]
CMakeDeps
CMakeToolchain
Install은 remote를 명시해서 실행합니다.
conan install . -r tirosh-conan --build=missing
6-3. 사용 예시¶
Conan package는 CMake target을 제공합니다.
find_package(patient_signal_c_core REQUIRED)
target_link_libraries(app PRIVATE tirosh::patient_signal_c_core)
6-4. 확인할 것¶
Conan package는 profile의 os, arch, compiler, build_type 영향을 받습니다. Binary가 없으면 --build=missing으로 source build가 가능한지 확인합니다.
7. Firmware / Raw Artifact¶
7-1. 다운로드¶
Firmware artifact는 dependency manager package가 아니라 raw repository artifact입니다. Consumer는 release manifest를 먼저 받고, manifest에 적힌 binary와 checksum을 기준으로 검증합니다.
export NEXUS_RAW_FIRMWARE_URL=https://nexus.internal.tirosh.ai/repository/raw-embedded-guide-hosted
curl --fail \
--user "$NEXUS_USERNAME:$NEXUS_PASSWORD" \
--output wearable-firmware.release-manifest.json \
"$NEXUS_RAW_FIRMWARE_URL/wearable-firmware/0.1.0/wearable-firmware.release-manifest.json"
7-2. 확인할 것¶
Firmware binary는 device lab, QA, manufacturing handoff에서 소비될 수 있습니다. 다운로드한 binary는 manifest의 checksum과 version metadata를 확인한 뒤 사용합니다.
8. Source Repo 안에서 검증할 때¶
8-1. Local helper 사용¶
Source repo를 clone한 상태에서 이 repo의 package 설치와 publish 설정을 검증한다면 make nexus/configure를 사용할 수 있습니다.
export NEXUS_USERNAME="..."
export NEXUS_PASSWORD="..."
export NEXUS_NPM_REGISTRY=https://nexus.internal.tirosh.ai/repository/npm/
export NEXUS_PYPI_INDEX_URL=https://nexus.internal.tirosh.ai/repository/pypi/simple/
export NEXUS_CARGO_PROXY_REGISTRY=sparse+https://nexus.internal.tirosh.ai/repository/cargo/
export NEXUS_CARGO_REGISTRY_INDEX=sparse+https://nexus.internal.tirosh.ai/repository/cargo-guide-hosted/
export NEXUS_GO_PROXY_URL=https://nexus.internal.tirosh.ai/repository/go/
export NEXUS_CONAN_REMOTE_URL=https://nexus.internal.tirosh.ai/repository/conan/
export NEXUS_RAW_FIRMWARE_URL=https://nexus.internal.tirosh.ai/repository/raw-embedded-guide-hosted
make nexus/configure
이 helper는 .npmrc, .cargo/config.toml, .nexus-go.env, Conan remote를 준비합니다. 생성 파일은 local credential을 포함할 수 있으므로 commit하지 않습니다.
8-2. Repo dependency 설치¶
Source repo 자체의 workspace dependency를 설치하려면 아래 명령을 사용합니다.
make package/install
이 명령은 consumer project의 일반 설치 명령이 아니라 source repo 개발용 shortcut입니다.
9. Troubleshooting¶
9-1. 자주 보는 실패¶
| 증상 | 먼저 확인할 것 |
|---|---|
401 Unauthorized 또는 403 Forbidden |
Nexus credential, repository read 권한, env variable 이름을 확인합니다. |
| Package not found | 해당 version이 release workflow에서 publish되었는지 확인합니다. |
| Public registry로 요청이 나감 | .npmrc, .cargo/config.toml, pyproject.toml index, GOPROXY가 Nexus를 보고 있는지 확인합니다. |
| Python wheel platform mismatch | consumer runtime의 OS/arch/Python version에 맞는 wheel이 publish되었는지 확인합니다. |
| Go module resolution 실패 | module tag, GOPROXY, GONOSUMDB, Git credential을 확인합니다. |
| Conan binary mismatch | Conan profile의 os, arch, compiler, build_type을 확인합니다. |
9-2. 다음에 볼 문서¶
Package를 publish하는 기준은 Release Policy를 봅니다. Nexus repository 운영 기준은 Nexus를 봅니다. CI에서 package와 image가 언제 build/push되는지는 CI/CD를 봅니다.