herzogfloria/Portfolio_Risk_Management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP: installer docs and quieter install step (test branch)

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
herzogflorian 2026-10-07 12:12:54 +02:00
parent 862aaf1b86
commit 30a4dfa4bb
4 changed files with 47 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
README.md
View File

@ -39,18 +39,17 @@ Apptainer, no root), [docs/SPARK_DEPLOYMENT.md](docs/SPARK_DEPLOYMENT.md) (the D
## Quick start on your DGX Spark (students)
The service and cuOpt run as two Apptainer containers on your Spark and talk over `127.0.0.1`.
No root rights, no Docker, nothing exposed to the network:
No root rights, no Docker, no git, nothing exposed to the network. One line in a terminal on the
Spark installs everything, builds the market data from Yahoo Finance and starts the service:
```bash
git clone https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management.git
cd Portfolio_Risk_Management
deploy/apptainer/qc.sh install # once: cuOpt image, quantcore image, self-test
deploy/apptainer/qc.sh data-import quantcore_data.tar.gz # prepared data set (or: qc.sh setup, ~15 min)
deploy/apptainer/qc.sh start # -> http://127.0.0.1:5001/ui/ and /docs
deploy/apptainer/qc.sh api selftest # every endpoint, pass/fail
wget -qO- https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh | bash
```
Your platform then calls the API at `http://127.0.0.1:5001`. The full guide, with settings,
Without `wget`, use `curl -fsSL https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh | bash`. With a prepared data set, add
`bash -s -- --data /path/to/quantcore_data.tar.gz` in place of the final `bash`. Afterwards the command `qc`
runs the service (`qc status`, `qc stop`, `qc start`, `qc upgrade`), the test bench is at
`http://127.0.0.1:5001/ui/`, and your platform calls the API at `http://127.0.0.1:5001`. The full guide, with settings,
several users on one Spark and troubleshooting, is [docs/SPARK_APPTAINER.md](docs/SPARK_APPTAINER.md).
## Quick start (local)

1
deploy/apptainer/qc.sh
View File

@ -281,6 +281,7 @@ cmd_install() {
step "Self-test of the quantcore container ($(qc_mode) mode)"
qc_selftest
[[ "${QC_FROM_INSTALLER:-0}" == 1 ]] && return 0 # install.sh does the data and the start itself
step "Data ($QC_DATA)"
if data_is_empty; then
say " empty. Either copy a prepared data set: $0 data-import quantcore_data.tar.gz"

58
docs/SPARK_APPTAINER.md
View File

@ -25,17 +25,39 @@ everything.
## Quick start
```bash
git clone https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management.git
cd Portfolio_Risk_Management
Open a terminal on the Spark and run this one line:
deploy/apptainer/qc.sh install # once, ~10 min: settings, cuOpt image, quantcore image, self-test
deploy/apptainer/qc.sh data-import /path/to/quantcore_data.tar.gz # the prepared data set
# or build the data set from Yahoo Finance yourself (~15 min): deploy/apptainer/qc.sh setup
deploy/apptainer/qc.sh start # starts cuOpt and the API
```bash
wget -qO- https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh | bash
```
Then open **http://127.0.0.1:5001/ui/** in the Spark's browser. The interactive API
If the Spark has no `wget`, one of these does the same:
```bash
curl -fsSL https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh | bash
python3 -c "import urllib.request as u;print(u.urlopen('https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh').read().decode())" | bash
```
The installer takes 20 to 30 minutes the first time and prints each step:
1. It checks Apptainer and the GPU. It also repairs Apptainer's temporary and cache folders if
your account points them at a folder that does not exist.
2. It downloads the code to `~/Portfolio_Risk_Management`. If the Spark has no git, it uses git
from a small container.
3. It gets the cuOpt image and the quantcore image.
4. It builds the market data from Yahoo Finance, which takes about 15 minutes.
5. It starts the service, runs the self-test and installs the command `qc`.
With a prepared data set from your lecturer, the data step takes seconds instead. Pass the file
with `--data`:
```bash
wget -qO- https://gitea.fhgr.ch/herzogfloria/Portfolio_Risk_Management/raw/branch/main/install.sh | bash -s -- --data ~/Downloads/quantcore_data.tar.gz
```
Running the installer again is safe. It skips what is done and updates the rest.
When it is done, open **http://127.0.0.1:5001/ui/** in the Spark's browser. The interactive API
documentation is at **http://127.0.0.1:5001/docs**.
Working on the Spark over SSH from your laptop? Forward the port, then open the same address in
@ -45,13 +67,8 @@ the laptop's browser. Nothing else on the network can reach the service:
ssh -L 5001:127.0.0.1:5001 <your-user>@<your-spark>
```
A shorter command saves typing. Put this line in your `~/.bashrc`:
```bash
alias qc="$HOME/Portfolio_Risk_Management/deploy/apptainer/qc.sh"
```
The rest of this guide writes `qc` for the script.
The installer puts the command `qc` into `~/.local/bin`. Open a new terminal once so that the
shell finds it. `qc` is the same as `deploy/apptainer/qc.sh` in the code folder.
## Daily use
@ -60,6 +77,7 @@ qc start # cuOpt + API; after a reboot, run it again
qc status # what runs, whether cuOpt is reachable, how much data there is
qc logs # API log; `qc logs cuopt` for the solver, add -f to follow
qc update # the newest prices and FX rates from Yahoo Finance
qc upgrade # the newest version of the code: download, rebuild, restart
qc stop # stop both containers
```
@ -140,11 +158,8 @@ with `QC_IMAGE=venv`.
`QC_IMAGE` also accepts the path of a prebuilt `quantcore.sif`, or a `docker://` or `oras://`
address to pull one from.
**After `git pull`**, rebuild and restart:
```bash
git pull && qc build && qc restart
```
**New versions of the code** come with `qc upgrade`. It downloads the changes, rebuilds quantcore
and restarts the service.
## How it works
@ -198,6 +213,9 @@ git pull && qc build && qc restart
| The cuOpt log says `Read-only file system: '/opt/cuopt/.cupy'` | cuOpt was started without `qc.sh`. Start it with `qc start`, or give it a writable home directory as described in "Running cuOpt by hand". |
| `/optimize` answers 503, "no market data yet" | Run `qc data-import <file>` or `qc setup`. |
| Yahoo errors during `qc setup` or `qc update` | Yahoo limits how fast it answers. Run the command again later; stored data stays intact. |
| `FATAL: ... failed to create build parent dir: stat /scratch/...` | Your account sets `APPTAINER_TMPDIR` to a folder that does not exist. The installer and `qc` now detect this, use a folder that works, and save the choice in `~/quantcore/quantcore.env`. Run the installer again. |
| `git: command not found` | Use the one-line installer. It needs no git. |
| `qc: command not found` right after the installation | Open a new terminal, or run `export PATH="$HOME/.local/bin:$PATH"`. |
| `qc install` stops with "no 'instance run'" | The Spark's Apptainer is older than 1.1. Ask the administrator to update it. |
| The cuOpt pull fails with "no space left on device" | Apptainer unpacks images in `/tmp`. Point it at a larger directory: `APPTAINER_TMPDIR=~/quantcore/tmp qc pull-cuopt`. |
| Model status `FeasibleFound` instead of `Optimal` | The time limit was reached. Raise `time_limit` in the request or `QUANTCORE_CUOPT_TIME_LIMIT`, or reduce `n_scenarios` or `max_assets`. |

2
install.sh
View File

@ -80,7 +80,7 @@ main() {
chmod +x "$qc" "$dir/install.sh" 2>/dev/null || true
step "3/5 Container images"
"$qc" install
QC_FROM_INSTALLER=1 "$qc" install
persist_fixes
if [[ -n "$before" && "$before" != "$after" ]]; then
say " the code changed since the last installation: rebuilding quantcore"