about summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-08 13:28:15 +0000
committerPjotr <wrk@bosa.lan>2026-11-08 13:28:15 +0000
commite5c2aa0ab1e568fe91c63cd5257aee7ff08ebed9 (patch)
tree3404fdf0a0c1a0cd34218832905bac0361074b64 /README.md
parentb8fdbb3d60603c07cacf9f406ed1a5c228223829 (diff)
downloadgenenetwork4-e5c2aa0ab1e568fe91c63cd5257aee7ff08ebed9.tar.gz
docs: what the last two commits changed, and the dev/production split
* README.md (Running with cargo): "This deployment runs two instances:
3000 (production) and 3001 (development)" -- the table of ports, binaries
and cache directories, both start-up invocations, and why the caches are
separate while the database, index and auth stub are shared. Also notes
that in-memory state is per instance, so the dev server is not a capacity
test of production.
* docs/www/ai-instruction.md:
  - /version now described honestly: git (with -dirty), dirty,
    source_digest, database reachable/unreachable -- and that
    `unreachable` means stop and report, not retry in a loop.
  - error table: 413 (plain text, not the JSON object: over the 64 MiB
    body limit), 500 database_error with a connection-loss detail is
    transient (retry once), and 409 run_id_in_use pointing at the status
    endpoint.
  - covariates: case_attribute is the smallest form (nothing posted),
    which is also the answer to a 413 from sending a value per individual.
Diffstat (limited to 'README.md')
-rw-r--r--README.md51
1 files changed, 51 insertions, 0 deletions
diff --git a/README.md b/README.md
index dd3716b..a0f5958 100644
--- a/README.md
+++ b/README.md
@@ -1565,6 +1565,57 @@ GENENETWORK4_PORT=8080 cargo run
 GENENETWORK4_BIND=127.0.0.1 cargo run
 ```
 
+### This deployment runs two instances: 3000 (production) and 3001 (development)
+
+The reference deployment keeps a development instance next to the live
+one, on the same box, so work can be tried out without disturbing what
+the site is serving:
+
+| instance | port | binary | run caches | proxied by nginx |
+|---|---|---|---|---|
+| **production** | `3000` | `target/release/genenetwork4` | defaults (`/tmp/gn4-gemma`, `/tmp/gn4-rqtl`, …) | yes, at `/gn4/` (see [docs/nginx.md](docs/nginx.md)) |
+| **development** | `3001` | `target/debug/genenetwork4` | `/tmp/gn4-dev/{gemma,rqtl,ravanan}` | no |
+
+They differ only in the port, the build profile and those cache
+directories; both use the same read-only `SQL_URI`, the same Xapian index
+and the same auth stub, so a request behaves the same on either. The
+separate caches matter: a GEMMA or R/qtl run on the development instance
+must not fill, or be sped up by, production's warm cache.
+
+```sh
+P=$(guix shell -D -f guix.scm -- bash -c 'echo $GUIX_ENVIRONMENT')   # needs R + gemma-wrapper on PATH
+
+# production
+PATH=$P/bin:$PATH R_LIBS_SITE=$P/site-library/ \
+GENENETWORK4_BIND=127.0.0.1 GENENETWORK4_PORT=3000 GENENETWORK4_TEST_TOKEN=false \
+AUTH_SERVER_URL=http://127.0.0.1:8081/ \
+SQL_URI=mysql://webqtlout:webqtlout@127.0.0.1/db_webqtl \
+XAPIAN_DB_PATH=/home/wrk/tmp/ai-root/factory/gn4-index SEARCH_ENGINE=native \
+nohup ./target/release/genenetwork4 > /tmp/gn4-3000.log 2>&1 &   # pid in /tmp/gn4.pid
+
+# development: same, plus the port and its own caches
+PATH=$P/bin:$PATH R_LIBS_SITE=$P/site-library/ \
+GENENETWORK4_BIND=127.0.0.1 GENENETWORK4_PORT=3001 GENENETWORK4_TEST_TOKEN=false \
+AUTH_SERVER_URL=http://127.0.0.1:8081/ \
+SQL_URI=mysql://webqtlout:webqtlout@127.0.0.1/db_webqtl \
+XAPIAN_DB_PATH=/home/wrk/tmp/ai-root/factory/gn4-index SEARCH_ENGINE=native \
+GEMMA_CACHE_DIR=/tmp/gn4-dev/gemma RQTL_CACHE_DIR=/tmp/gn4-dev/rqtl \
+RAVANAN_CACHE_DIR=/tmp/gn4-dev/ravanan \
+nohup ./target/debug/genenetwork4 > /tmp/gn4-dev.log 2>&1 &   # pid in /tmp/gn4-dev.pid
+```
+
+Both need the `PATH`/`R_LIBS_SITE` pair (see "Building with cargo, outside
+a bare toolchain" below) or R/qtl fails with `there is no package called
+'optparse'`, and both need the auth stub on `127.0.0.1:8081` to serve
+`/auth/public-jwks` (see "Tests").
+
+Anything the server keeps in memory is per instance: the pool, the JWKS
+and authorisation caches, and any in-process compute limit. So the two
+instances do not serialise against each other — a mapping on `:3001` runs
+alongside one on `:3000` — which is the point of the split, and a good
+reason not to treat the development instance as a capacity test of what
+production will do.
+
 ### Building with cargo, outside a bare toolchain
 
 `cargo build` in the package's own dependency shell is the supported