From 575ee2eaf542bb9af396a99963787f9ec0512175 Mon Sep 17 00:00:00 2001 From: Dhravya Shah Date: Mon, 12 Oct 2026 16:54:58 -0700 Subject: [PATCH] docs: add Docker installation and safe upgrade instructions (#1801) --- README.md | 18 +++++ apps/docs/docs.json | 1 + apps/docs/self-hosting/docker.mdx | 109 ++++++++++++++++++++++++++ apps/docs/self-hosting/quickstart.mdx | 2 + 4 files changed, 130 insertions(+) create mode 100644 apps/docs/self-hosting/docker.mdx diff --git a/README.md b/README.md index 6c2daacc..11474bc7 100644 --- a/README.md +++ b/README.md @@ -340,6 +340,24 @@ const client = new Supermemory({ - **Your data, one directory** — everything lives in `./.supermemory`, easy to back up or move. - **Same API as the platform** — prototype locally, ship on the hosted platform by changing `baseURL`. +### Run with Docker + +Prebuilt images support Linux amd64 and arm64. You don’t need to build or clone the server source. + +For a new installation, run these commands in an empty directory and set your own LLM provider key: + +```bash +release_url=https://github.com/supermemoryai/supermemory/releases +curl -fL "$release_url/download/server-v0.0.9/compose.yaml" -o compose.yaml +export OPENAI_API_KEY=your_openai_api_key_here +export SUPERMEMORY_VERSION=0.0.9 +docker compose up -d --wait --wait-timeout 180 +``` + +The API listens on `http://localhost:6767`. Data and credentials persist in the `supermemory_supermemory-data` volume. Get your local API key with `docker compose exec supermemory cat /data/api-key`; requests require it even on localhost. + +Read the [Docker setup and upgrade instructions](apps/docs/self-hosting/docker.mdx) for persistent provider configuration, backups and upgrades. Keep the existing volume and keys when upgrading; **don’t run `docker compose down -v`**. + Read the [self-hosting docs](https://supermemory.ai/docs/self-hosting/overview) — quickstart, [configuration](https://supermemory.ai/docs/self-hosting/configuration), [embeddings](https://supermemory.ai/docs/self-hosting/embeddings), and [local vs. Enterprise](https://supermemory.ai/docs/self-hosting/local-vs-enterprise). --- diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 04c24a0f..6482fce4 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -216,6 +216,7 @@ "pages": [ "self-hosting/overview", "self-hosting/quickstart", + "self-hosting/docker", "self-hosting/configuration", "self-hosting/embeddings", "self-hosting/providers", diff --git a/apps/docs/self-hosting/docker.mdx b/apps/docs/self-hosting/docker.mdx new file mode 100644 index 00000000..1693c9fd --- /dev/null +++ b/apps/docs/self-hosting/docker.mdx @@ -0,0 +1,109 @@ +--- +title: "Run Supermemory with Docker" +sidebarTitle: "Docker" +description: "Start the prebuilt Local image, keep your data, and upgrade an existing Compose installation." +icon: "docker" +--- + +Run Supermemory Local with the prebuilt Docker image. Docker chooses the Linux amd64 or arm64 image for your machine. You don’t need the server source, a local build, or a registry login. + +You need Docker with the Compose plugin. Docker Desktop on macOS or Windows must run Linux containers. These shell examples use Bash or a compatible shell. + +## Start a new installation + +Use an empty directory for this installation. If you already run Supermemory with Compose, follow [Upgrade an existing installation](#upgrade-an-existing-installation) instead of overwriting your configuration. + +Download the Compose file from the [0.0.9 release](https://github.com/supermemoryai/supermemory/releases/tag/server-v0.0.9): + +```bash +release_url=https://github.com/supermemoryai/supermemory/releases +curl -fL "$release_url/download/server-v0.0.9/compose.yaml" -o compose.yaml +``` + +Create a `.env` file beside `compose.yaml`, replacing the placeholder with your provider key: + +```dotenv +OPENAI_API_KEY=your_openai_api_key_here +SUPERMEMORY_VERSION=0.0.9 +``` + +You can use `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `GROQ_API_KEY` instead of OpenAI. Keep `.env` private and don’t commit it. Docker runs non-interactively, so there’s no first-boot provider wizard. + +Protect the file, pull the image, and start the service: + +```bash +chmod 600 .env +unset SUPERMEMORY_VERSION +docker compose pull +docker compose up -d --wait --wait-timeout 180 +docker compose ps +``` + +The published image is `docker.io/supermemory/supermemory`. `SUPERMEMORY_VERSION=0.0.9` pins this release; `latest` follows stable releases. The Compose file binds port `6767` to `127.0.0.1`, not the public network. Allow the first startup to finish before checking health: + +```bash +curl --fail http://127.0.0.1:6767/v3/health +``` + +Local embeddings are the default. The first model download needs network access, and your chosen LLM provider may make external requests. + +## Authenticate API requests + +The server creates a local API key, separate from your LLM provider key. The Docker image hides that key from startup logs, so read it from the container: + +```bash +SUPERMEMORY_API_KEY="$(docker compose exec -T supermemory cat /data/api-key)" +curl --fail -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ + http://127.0.0.1:6767/v3/projects +``` + +Treat this key as a secret. API requests require it even on localhost. Use the same key with your SDK and set `baseURL` to `http://localhost:6767`. + +## Preserve data and configuration + +The Compose project name is fixed as `supermemory`. Its named volume, `supermemory_supermemory-data`, mounts at `/data` and contains your store, API key, encryption identity, configuration, and model cache. Container replacement keeps that volume. + + +Don’t run `docker compose down -v` or delete the volume: that removes your stored data and credentials. Keep the project name and volume mapping unchanged when upgrading. Changing the provider or embedding settings is a separate operation. + + +The Compose file passes through the provider keys listed above and `FIRECRAWL_API_KEY`. To disable telemetry, add `SUPERMEMORY_DISABLE_TELEMETRY=1` to `.env`. Other [configuration variables](/self-hosting/configuration) need entries in the service’s `environment` block; setting them only in the host shell doesn’t pass them into the container. + +## Upgrade an existing installation + +Back up the complete stopped store before replacing its image. Run these commands from the directory containing your existing Compose file. + +### Back up the store + +Stop the service, then copy everything under `/data`, including its keys and identity files: + +```bash +docker compose stop +backup_dir="backups/$(date -u +%Y%m%dT%H%M%SZ)" +mkdir -p "$backup_dir" +chmod 700 "$backup_dir" +docker compose cp supermemory:/data/. "$backup_dir/" +``` + +Keep this backup and your existing `.env` file private. Confirm the copy completed before upgrading. These steps cover an existing Docker store; moving a native installation into Docker requires preserving that installation’s complete store and keys separately. + +### Pull and start the new image + +Keep your existing Compose configuration. If it uses an older GHCR image reference, change only its `image` line to the public Docker Hub image: + +```yaml +image: docker.io/supermemory/supermemory:${SUPERMEMORY_VERSION:-latest} +``` + +Set `SUPERMEMORY_VERSION=0.0.9` in your existing `.env`, then pull and recreate the service without deleting its volume. Unset a previously exported version so `.env` takes precedence: + +```bash +unset SUPERMEMORY_VERSION +docker compose pull +docker compose up -d --wait --wait-timeout 180 +curl --fail http://127.0.0.1:6767/v3/health +``` + +Local verifies a complete original backup before migrating an existing store. Existing cleanup can remove older duplicate documents and their source links. Keep your manual backup too; don’t point an older image at a migrated store. To roll back, restore the complete pre-upgrade backup and use its matching previous version. + +Native Windows remains on 0.0.8; these Docker images run Linux containers. diff --git a/apps/docs/self-hosting/quickstart.mdx b/apps/docs/self-hosting/quickstart.mdx index cafd5141..787f1979 100644 --- a/apps/docs/self-hosting/quickstart.mdx +++ b/apps/docs/self-hosting/quickstart.mdx @@ -76,6 +76,8 @@ In production, Supermemory runs proprietary models tuned for long-horizon data u **Docker / non-interactive:** set an LLM key via env and, if you don’t want local embeddings, set `SUPERMEMORY_EMBEDDING_PROVIDER` / `MODEL` / `DIMENSIONS`. There is no wizard without a TTY. +For the prebuilt Docker image, follow [Run Supermemory with Docker](/self-hosting/docker) for installation, authentication, backups, and upgrades. + ## Add your first memory