Deploy on Google Cloud (Marketplace VM)

The GoodMem Google Cloud Marketplace listing deploys one self-managed GoodMem VM. You provide an external PostgreSQL database, and the image provides everything else. GoodMem starts automatically on boot.

Getting GoodMem running takes just five steps: prepare a database, launch the VM, connect to it, initialize GoodMem, and open the console. The later sections, Advanced configuration and Operating the VM, are optional and there for when you need them.

1. Prepare a PostgreSQL database

GoodMem stores all of its data in an external PostgreSQL 17 database that the VM connects to. You only need to provide an empty database. GoodMem builds its own tables and enables the extensions it needs (pgvector and a few others) on first boot, so you never run any schema SQL yourself.

To get ready, make sure you have:

1. A PostgreSQL 17 instance reachable from the VM. Cloud SQL for PostgreSQL 17, AlloyDB, or a self-managed instance all work.
2. An empty database and a user/role that GoodMem connects as, with permission to create tables and extensions in it. On managed PostgreSQL the default admin user (for example, Cloud SQL's postgres) already has this.
3. pgvector available. It is built in on Cloud SQL and AlloyDB; on a self-managed instance, install the pgvector package for PostgreSQL 17.

2. Launch the VM

Deploy from the Marketplace listing. The only required input is your database connection string; everything else has a sensible default. Configuration is passed as GCE instance metadata, which the deployment form fills in for you:

That is all you need for a standard deployment. TLS defaults to a self-signed certificate (HTTPS that clients reach with curl -k). To turn TLS off, use your own certificate, or get a real Let's Encrypt certificate, see Advanced configuration.

GoodMem also supports many additional GOODMEM_* settings for finer-grained configuration. If you want that level of control, see the server settings for what is available and Extra environment variables for how to set them on this VM.

If goodmem-database-url is not set, GoodMem does not start. First boot fails loudly, and the reason is shown by sudo goodmem-status on the VM.

3. Connect to the VM and check status

SSH password authentication is disabled on this image. Connect with an SSH key over Identity-Aware Proxy (IAP). Both options use Google's standard SSH key management, so there is no manual key setup:

• Console SSH button (zero-config): Google Cloud Console → Compute Engine → VM instances → click your VM → SSH. A browser terminal opens with passwordless sudo.

• gcloud from your terminal (note: no username@ prefix):

  gcloud compute ssh VM_NAME --project=YOUR_PROJECT --zone=YOUR_ZONE --tunnel-through-iap

Once connected, check that GoodMem came up and reached your database:

sudo goodmem-status        # firstboot, server, and database readiness in one view

You are ready for the next step once the server is running and /readyz reports healthy.

4. Initialize and get your API key

A fresh server has no users and no API keys. Running init once creates the root user and returns the root API key. The CLI is pre-installed on the VM, so run this from within the VM (the session you opened in step 3).

# self-signed (default): gRPC over TLS, skip cert verification
goodmem init --server https://localhost:9090 --insecure --save-config

# tls-mode=disabled: plain http instead
goodmem init --server http://localhost:9090 --save-config

# self-signed:
curl -k -X POST https://localhost:8080/v1/system/init
# disabled:
curl    -X POST http://localhost:8080/v1/system/init
# -> {"rootApiKey":"gm_..."}

Use the key for subsequent calls, either via the saved CLI config or by exporting it:

export GOODMEM_API_KEY=gm_...
goodmem system health

See the CLI init reference for more.

5. Open the web console

GoodMem serves a web console directly from the REST port. Open it in your browser at:

https://VM_EXTERNAL_IP:8080/console/

The console prompts for an API key on load. Paste the root API key from step 4.

That is the full happy path. The rest of this page is optional.

Advanced configuration

A couple of options need file contents (a TLS certificate, or a block of environment variables) rather than a short string. You supply those through one special instance-metadata key, user-data, whose value is a cloud-init #cloud-config document. Set it the same way you set the other metadata, either:

• Console: when creating or editing the VM, open Advanced options → Management → Metadata, add an item with key user-data, and paste the document as the value; or
• gcloud: --metadata-from-file user-data=cloud-init.yaml

GoodMem reads the files cloud-init writes when it boots.

TLS modes

goodmem-tls-mode selects how GoodMem serves HTTPS:

Bring your own certificate (byo)

Set goodmem-tls-mode=byo, then provide your PEM cert and key through the user-data metadata key (base64-encode each with base64 -w0):

#cloud-config
write_files:
  - path: /etc/goodmem/tls/server.crt
    permissions: '0644'
    owner: root:root
    encoding: b64
    content: <base64 of server.crt>
  - path: /etc/goodmem/tls/server.key
    permissions: '0600'
    owner: root:root
    encoding: b64
    content: <base64 of server.key>

Let's Encrypt (acme)

Let's Encrypt must reach your DNS name at the VM's external IP, but that IP does not exist until the VM is created. To avoid this chicken-and-egg, reserve a static external IP and point your DNS at it before deploying. Then set goodmem-tls-mode=acme plus these metadata keys:

Also allow inbound TCP/5002 from the public internet; Let's Encrypt uses it for HTTP-01 validation. Clients still use 8080/9090.

Extra environment variables

Any GOODMEM_* setting the server supports can be supplied by writing /etc/goodmem/goodmem-user.env via the user-data metadata key. It is loaded after the metadata-derived config, so it overrides first-boot defaults:

#cloud-config
write_files:
  - path: /etc/goodmem/goodmem-user.env
    permissions: '0600'
    owner: root:root
    content: |
      GOODMEM_SOME_FLAG=value
      GOODMEM_ANOTHER_SETTING=value

Applying changes to a running VM

The same paths work after boot. Write the file over SSH, then re-apply:

# BYO cert (re-runs first boot to copy the cert in and restart GoodMem):
sudo install -m 644 server.crt /etc/goodmem/tls/server.crt
sudo install -m 600 server.key /etc/goodmem/tls/server.key
sudo goodmem-firstboot

# Extra env vars (a plain restart is enough):
sudo tee -a /etc/goodmem/goodmem-user.env >/dev/null <<'EOF'
GOODMEM_SOME_FLAG=value
EOF
sudo systemctl restart goodmem.service

Operating the VM

Useful commands

sudo goodmem-status            # health overview (first boot, server, /readyz)
goodmem version                # CLI version
sudo goodmem-support-bundle    # collect redacted logs for support

Good to know

• Data lives in your database. Embeddings, memories, users, and API keys are all stored in the PostgreSQL database you supplied, not on the VM disk. Back up the database, not the VM.
• The VM holds config and TLS state. /etc/goodmem/ (rendered config) and /var/lib/goodmem/ (TLS certs, ACME state) persist across reboots. A reboot needs no reconfiguration.
• Restarting the server: sudo systemctl restart goodmem.service. To re-apply a config or certificate change, run sudo goodmem-firstboot.
• Upgrading GoodMem: deploy a new VM from the newer Marketplace image pointed at the same database; the schema migrates on start. This appliance does not upgrade the baked server image in place.
• One server, one VM. This listing is a single server-only VM against an external database, with no built-in HA, load balancing, or autoscaling.

What you are responsible for

This is a self-managed appliance. You own production networking and firewall rules, database provisioning and backups, TLS certificates, monitoring, and scaling.

Next steps