Installation and Upgrade of GoodMem

Installing in a network-restricted environment

The default installer fetches from these upstream hosts:

get.goodmem.ai — the GoodMem CLI tarball
get.docker.com — the Docker engine installer (only when Docker is not yet installed)
ghcr.io — the GoodMem server image
docker.io — the PostgreSQL+pgvector image
sigstore.dev — signature material for cosign verification

When any of these is unreachable — typically inside a corporate firewall or in mainland China — the installer accepts a small set of flags that let you complete an install using a pre-staged CLI tarball plus a reachable registry mirror.

This page walks through the canonical setup using Nanjing University's public mirrors (ghcr.nju.edu.cn and docker.nju.edu.cn) as the example. Substitute your own internal mirror hosts if you have them.

Prerequisites

Docker engine is already installed and reachable. The installer's auto-install path calls get.docker.com, which may also be blocked. On Debian/Ubuntu inside China, configure a Docker Hub mirror in /etc/docker/daemon.json once (e.g. https://docker.nju.edu.cn) and sudo systemctl restart docker.
Two files delivered out of band (email, scp, internal object storage):
- install.sh — the bash entry point (the same file served at https://get.goodmem.ai).
- goodmem-<os>-<arch>.tar.gz — the CLI tarball matching the target platform (e.g. goodmem-linux-amd64.tar.gz).
A reachable mirror of ghcr.io that proxies pair-systems-inc/goodmem/server, such as ghcr.nju.edu.cn.
A reachable mirror of docker.io that proxies pgvector/pgvector, such as mirror.gcr.io (Google's public Docker Hub proxy — globally reachable and proxies the full Docker Hub namespace).

Not every Docker Hub mirror proxies every namespace — at the time of writing docker.nju.edu.cn returns 403 for pgvector/pgvector while serving other images fine. Before installing, verify with:
```
docker pull <your-mirror>/pgvector/pgvector:pg17
```
If that fails, pick a different mirror or rely on a daemon-level registry-mirrors config in /etc/docker/daemon.json instead.

Install command

bash install.sh \
  --local-cli-tarball ./goodmem-linux-amd64.tar.gz \
  --goodmem-image ghcr.nju.edu.cn/pair-systems-inc/goodmem/server:latest \
  --pgvector-image mirror.gcr.io/pgvector/pgvector:pg17 \
  --skip-verify \
  --handsfree --db-password "your-secure-password-min-14-chars" \
  --tls-disabled

What each flag does:

Flag	Effect
`--local-cli-tarball <path>`	Use this tarball instead of downloading from `get.goodmem.ai`.
`--goodmem-image <ref>`	Override the GoodMem server image — point at a mirrored registry (e.g. `ghcr.nju.edu.cn/...`).
`--pgvector-image <ref>`	Override the pgvector image — point at a mirrored Docker Hub (e.g. `mirror.gcr.io/...`).
`--skip-verify`	Skip cosign SLSA verification, which requires `sigstore.dev`. See the security note below.

The image choices are sticky: they get stamped into the per-profile .env file under ~/.goodmem/installs/local-docker/<profile>/. Subsequent goodmem system upgrade runs reuse the same images automatically — no need to repeat the flags on every upgrade.

Security note about `--skip-verify`

--skip-verify turns off the cosign SLSA-provenance check that normally proves the image you pulled was built by GoodMem's CI from this repository. Without it, you are trusting whatever bytes the mirror serves.

The mirror caching is content-addressable (an OCI manifest digest can't be forged without breaking SHA-256), so a benign mirror cannot serve a different image. The remaining risk is a stale mirror serving an older version, or a malicious mirror serving its own build. Two ways to harden:

Pin a digest. Pass --goodmem-image ghcr.nju.edu.cn/pair-systems-inc/goodmem/server@sha256:... with the digest you cross-checked against upstream. The installer then pulls that exact content.
Manually verify. If your network reaches sigstore.dev intermittently (e.g., via a VPN), run cosign verify-attestation --type slsaprovenance ... against the mirror before approving the install for production use.

Upgrading

First, obtain the new CLI tarball. Ask your contact at PAIR Systems for the latest release.

Then, manually upgrade Goodmem CLI without network access:

goodmem upgrade --local-cli-tarball ./goodmem-linux-amd64.tar.gz --yes

Then you can upgrade the GoodMem server image. The command below pulls from the mirror configured at install time. --skip-cli-check bypasses the version gate that contacts get.goodmem.ai; --skip-verify mirrors the install-time choice.

goodmem system upgrade --skip-cli-check --skip-verify

Version discovery

Without get.goodmem.ai, the CLI cannot tell you "a new version is available". You'll need to learn about new releases out of band (mailing list, internal portal, GitHub Releases on a reachable network) and bring the new goodmem-<os>-<arch>.tar.gz over to the target machine, then run goodmem upgrade --local-cli-tarball .... The server side picks up the matching image automatically on the next goodmem system upgrade.