Deploy Astermem

Deploy AsterMem

Target state: AsterMem runs via Docker Compose (fixed port 8768, listening on localhost only) on a machine the user chooses, exposed to the internet with HTTPS — either through Cloudflare Tunnel or a Caddy reverse proxy. All data is persisted in that machine's data/ directory.

The process is executed by you (the agent) — locally or over SSH, do not throw commands at the user to run themselves. Check the output of each step before proceeding to the next. But do not touch anything before Step 0: ask the user what they want first.

Step 0: Ask What the User Wants (before doing anything)

Ask up front (use AskQuestion if available; ask only for what's missing):

1. Where should it run?
   • Path A — Cloud server / VPS: the user has one or is willing to rent one. Full flow: Steps 1–6
   • Path B — A machine the user already owns: this computer, a home NAS, a Raspberry Pi, a spare PC. No public IP, no port forwarding, no server rental — exposed through Cloudflare Tunnel for free. Flow: "Path B" section below, then Step 6
   • Path C — LAN only: no public access needed. Just run Step 4 on the machine and stop; remind the user to change the default password
2. Domain: does the user have one, and is it managed on Cloudflare? Path B requires a domain on Cloudflare (free plan; moving nameservers takes minutes, done once). Path A works with any domain (Caddy route) or none (IP + port)
3. Region: for mainland China servers, a bound domain requires ICP filing (Path B and the IP direct route don't involve filing); Docker Hub and GitHub may need mirror acceleration
4. Model API Key (optional): any of Bailian / OpenRouter / Google AI / Asterove, for semantic search. Not required to start — can be configured later in the Web UI

Choosing a Platform (Path A, if the user has no server yet)

AsterMem is a stateful long-running process (SQLite + on-disk vector index, all data in data/), so it needs a real machine — before recommending a rental, remind the user that Path B (a machine they already own + Cloudflare Tunnel) costs nothing:

• AWS: EC2, or Lightsail for a cheaper and simpler fixed-price VPS. Launch an Ubuntu instance and the workflow below applies as-is
• Alibaba Cloud: ECS or Simple Application Server. Mainland regions require ICP filing to bind a domain; Hong Kong / Singapore regions do not
• Cloudflare: Not for hosting — but recommended in front of the server for DNS + free HTTPS + hiding the origin IP. Cloudflare Tunnel replaces the reverse proxy entirely and is the preferred exposure route (Step 5, Option A)
• Vercel: ❌ Not suitable. Serverless platforms have no persistent disk and cannot run a long-lived process, so AsterMem cannot run there

Path B: No Server — a Machine You Already Own + Cloudflare Tunnel

cloudflared opens an outbound-only tunnel to Cloudflare's edge, so the machine needs no public IP, no router port forwarding, and no inbound firewall rules. Free plan is enough. Trade-off to state clearly: availability is tied to that machine and its network — it must stay powered on and online.

1. Reach the machine: if it is the computer you are running on, work locally. If it is a NAS / Raspberry Pi on the LAN, connect over SSH first (Step 2 applies unchanged)
2. Run AsterMem: if it is already running (e.g. via ./start.sh), reuse it — read the port from config.yaml. Otherwise start it with Docker (Step 4; keep the 127.0.0.1:8768:8768 mapping)
3. Install cloudflared:
   • macOS: brew install cloudflared
   • Debian/Ubuntu (incl. Raspberry Pi OS): use the apt source from Step 5 Option A
   • NAS with Docker only: run the cloudflare/cloudflared container with the dashboard token instead
4. Create the tunnel: exactly the commands in Step 5 Option A, pointing the ingress service at the actual local port. On macOS, cloudflared service install registers a launchd service; on Linux, systemd
5. Keep it alive: the service starts on boot on both platforms. On a laptop/desktop, disable system sleep (macOS: sudo pmset -a sleep 0, or System Settings → prevent sleep when on power) — a sleeping machine means an offline memory service
6. Verify https://<domain>/api/auth/check, then go straight to Step 6 (hardening is mandatory — the service is now public)

Step 1: DNS Resolution (Path A)

If going the Cloudflare Tunnel route (Step 5, Option A): no A record is needed — the tunnel creates the DNS record itself. Just confirm the domain's nameservers point to Cloudflare (dig NS example.com), then skip ahead.

Otherwise (Caddy route): have the user add an A record at their domain registrar: mem.example.com → server IP. Then verify locally — do not start installing Caddy until DNS has propagated (certificate issuance will fail):

dig +short mem.example.com   # should output the server IP

Step 2: Establish SSH Connection

When using password login, install the local public key on the server first for passwordless access going forward:

ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 2>/dev/null || true   # skip if exists
ssh-copy-id -p <port> <user>@<server_ip>   # enter password once interactively

If ssh-copy-id cannot run interactively, fall back to sshpass (macOS: brew install sshpass). Pass the password via environment variable — never write plaintext passwords into scripts, files, or commit history:

sshpass -p "$SSH_PASS" ssh -o StrictHostKeyChecking=accept-new -p <port> <user>@<server_ip> 'echo ok'

Once connected, probe the environment:

ssh <user>@<server_ip> 'cat /etc/os-release; docker --version; docker compose version'

Step 3: Install Docker (if missing)

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

For mainland China servers, if image pulls time out, configure mirror acceleration in /etc/docker/daemon.json then systemctl restart docker.