Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript

build: add container image, compose file, and VPS deployment guide

Alan Buscagliaee741484df02
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..0edaea1
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,9 @@
+**/node_modules
+**/dist
+.git
+apps/desktop/src-tauri/target
+apps/desktop/src-tauri/gen
+test-results
+playwright-report
+odd
+.atl
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..7321e43
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,41 @@
+# Gentle Dot for a server (for example a HostGator VPS). See docs/deploy-vps.md.
+
+FROM golang:1-bookworm AS engram
+RUN go install github.com/Gentleman-Programming/engram/v3/cmd/engram@latest
+
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/protocol/package.json packages/protocol/
+COPY packages/daemon/package.json packages/daemon/
+COPY packages/ui/package.json packages/ui/
+COPY apps/desktop/package.json apps/desktop/
+RUN pnpm install --frozen-lockfile
+COPY packages packages
+COPY tsconfig.base.json ./
+RUN pnpm --filter @gentle-dot/ui build
+
+FROM node:24-bookworm-slim
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl git tini \
+ && rm -rf /var/lib/apt/lists/* \
+ && npm install -g gentle-pi \
+ # The companion-package setup needs `pi` on PATH; match the version gentle-pi bundles.
+ && PI_VERSION="$(node -p "require('$(npm root -g)/gentle-pi/node_modules/@earendil-works/pi-coding-agent/package.json').version")" \
+ && npm install -g "@earendil-works/pi-coding-agent@${PI_VERSION}" \
+ && useradd --create-home dot \
+ # gentle-pi installs its gentle-ai binary as root with mode 0700; the agent runs as dot.
+ && chown -R dot:dot "$(npm root -g)/gentle-pi/.gentle-ai"
+COPY --from=engram /go/bin/engram /usr/local/bin/engram
+COPY --from=build /app /app
+COPY docker/entrypoint.sh /usr/local/bin/gentle-dot-entrypoint
+USER dot
+WORKDIR /home/dot
+ENV GENTLE_DOT_HOST=0.0.0.0 \
+ GENTLE_DOT_PORT=4317 \
+ GENTLE_DOT_DATA_DIR=/home/dot/.gentle-dot \
+ GENTLE_DOT_WORKSPACE=/home/dot/workspace
+EXPOSE 4317
+HEALTHCHECK --interval=30s --timeout=5s CMD node -e "fetch('http://127.0.0.1:4317/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
+ENTRYPOINT ["tini", "--", "gentle-dot-entrypoint"]
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 0000000..91b2ea3
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,37 @@
+# Gentle Dot on a server. Create .env first (docs/deploy-vps.md, step 3).
+# Default: the daemon listens on the VPS loopback only, and the existing web server
+# (Apache on a cPanel/WHM VPS such as HostGator) proxies HTTPS to it.
+# Without a web server, start the bundled Caddy too: docker compose --profile caddy up -d
+services:
+ gentle-dot:
+ build: .
+ restart: unless-stopped
+ environment:
+ GENTLE_DOT_ALLOWED_ORIGINS: '["https://${DOT_DOMAIN}"]'
+ ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+ OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+ volumes:
+ - dot-home:/home/dot
+ ports:
+ - "127.0.0.1:${DOT_PORT:-4317}:4317"
+
+ caddy:
+ image: caddy:2
+ profiles: ["caddy"]
+ restart: unless-stopped
+ depends_on:
+ - gentle-dot
+ environment:
+ DOT_DOMAIN: ${DOT_DOMAIN}
+ DOT_USER: ${DOT_USER:-}
+ DOT_PASSWORD_HASH: ${DOT_PASSWORD_HASH:-}
+ ports:
+ - "80:80"
+ - "443:443"
+ volumes:
+ - ./docker/Caddyfile:/etc/caddy/Caddyfile:ro
+ - caddy-data:/data
+
+volumes:
+ dot-home:
+ caddy-data:
diff --git a/docker/Caddyfile b/docker/Caddyfile
new file mode 100644
index 0000000..55bd7ca
--- /dev/null
+++ b/docker/Caddyfile
@@ -0,0 +1,7 @@
+{$DOT_DOMAIN} {
+ encode zstd gzip
+ basic_auth {
+ {$DOT_USER} {$DOT_PASSWORD_HASH}
+ }
+ reverse_proxy gentle-dot:4317
+}
diff --git a/docker/apache-gentle-dot.conf b/docker/apache-gentle-dot.conf
new file mode 100644
index 0000000..449fe45
--- /dev/null
+++ b/docker/apache-gentle-dot.conf
@@ -0,0 +1,22 @@
+# Apache reverse proxy for Gentle Dot on a cPanel/WHM VPS (HTTPS vhost include).
+# Replace dot.example.com and 4317 (DOT_PORT). Requires mod_proxy, mod_proxy_http,
+# mod_proxy_wstunnel, and mod_rewrite (enabled by default in EasyApache 4).
+<IfModule mod_proxy.c>
+ ProxyPreserveHost On
+ ProxyRequests Off
+
+ <Location />
+ AuthType Basic
+ AuthName "Gentle Dot"
+ AuthUserFile /etc/apache2/gentle-dot.htpasswd
+ Require valid-user
+ </Location>
+
+ RewriteEngine On
+ RewriteCond %{HTTP:Upgrade} =websocket [NC]
+ RewriteRule ^/ws$ ws://127.0.0.1:4317/ws [P,L]
+
+ ProxyPass /ws ws://127.0.0.1:4317/ws
+ ProxyPass / http://127.0.0.1:4317/
+ ProxyPassReverse / http://127.0.0.1:4317/
+</IfModule>
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
new file mode 100755
index 0000000..aad8977
--- /dev/null
+++ b/docker/entrypoint.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+# Starts the memory server, then the Gentle Dot daemon in the foreground.
+set -eu
+mkdir -p "$GENTLE_DOT_DATA_DIR" "$GENTLE_DOT_WORKSPACE"
+if command -v engram >/dev/null 2>&1; then
+ engram serve >"$GENTLE_DOT_DATA_DIR/engram.log" 2>&1 &
+fi
+exec node /app/packages/daemon/src/cli.ts
diff --git a/docs/deploy-vps.md b/docs/deploy-vps.md
new file mode 100644
index 0000000..5b76d7a
--- /dev/null
+++ b/docs/deploy-vps.md
@@ -0,0 +1,125 @@
+# Deploy Gentle Dot on a VPS
+
+This guide puts the same daemon you run locally on a server, so you can open Gentle Dot from any browser. It targets a HostGator VPS with cPanel/WHM, and also covers a plain VPS.
+
+> Status: documented, not executed. The local setup is the supported path today.
+
+## Before you start: what you are exposing
+
+Gentle Dot can read and write files and run commands. On a server, whoever reaches it controls that container. Keep these rules:
+
+- **HTTPS only.** Never expose port 4317 directly; the container binds the VPS loopback (`127.0.0.1`) on purpose.
+- **Two locks.** Use the web server password (Basic Auth) *and* the Gentle Dot access key.
+- **Isolated machine.** The agent works inside its container volume. Never mount your personal folders, SSH keys, or another project's data.
+- **Your model key is a secret.** Keep it only in the server's `.env` file with `chmod 600`, and never commit it.
+
+## What runs
+
+```
+browser ──HTTPS──▶ Apache (cPanel) or Caddy ──▶ 127.0.0.1:4317 ──▶ container: gentle-dot daemon
+ ├─ gentle-shell (agent)
+ └─ engram serve (memory)
+```
+
+The image (`Dockerfile`) installs `gentle-pi` (it provides `gentle-shell`), builds Engram, and builds the web UI. The `dot-home` volume keeps conversations, memory, the access key, and the agent login across restarts.
+
+## Steps
+
+### 1. Point a subdomain at the VPS
+
+Create an `A` record, for example `dot.example.com`, pointing to the VPS. Wait until it resolves:
+
+```bash
+dig +short dot.example.com
+```
+
+### 2. Get the code on the server
+
+```bash
+sudo mkdir -p /opt/gentle-dot && sudo chown "$USER" /opt/gentle-dot
+git clone <your-repository-url> /opt/gentle-dot
+cd /opt/gentle-dot
+```
+
+### 3. Create `.env`
+
+```bash
+cat > .env <<'EOF'
+DOT_DOMAIN=dot.example.com
+DOT_PORT=4317
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+EOF
+chmod 600 .env
+```
+
+Fill in one model key. If you prefer to log in to a provider instead of using a key, do it once after step 4 with `docker compose run --rm gentle-dot gentle-shell`; the login is kept in the volume.
+
+For the Caddy option, also add `DOT_USER` and `DOT_PASSWORD_HASH`. Generate the hash with `docker run --rm caddy:2 caddy hash-password --plaintext 'your-password'`, and write every `$` as `$$`.
+
+### 4. Build and start
+
+```bash
+docker compose up -d --build
+curl -s http://127.0.0.1:4317/health # {"ok":true,"agentState":"idle"}
+docker compose logs gentle-dot | grep "Gentle Dot is running"
+```
+
+The log line prints the URL with the access key, `http://127.0.0.1:4317/#token=…`. Keep the part after `#token=`; you will open it with your domain in step 6.
+
+### 5a. HostGator VPS (cPanel/WHM): Apache in front
+
+cPanel's Apache already owns ports 80 and 443, so Apache proxies to the container:
+
+1. Issue the certificate for the subdomain with AutoSSL in WHM, or with the server's usual Certbot method.
+2. Create the password file:
+ ```bash
+ sudo htpasswd -c /etc/apache2/gentle-dot.htpasswd me
+ ```
+3. Copy `docker/apache-gentle-dot.conf` into the HTTPS include folder for the subdomain, for example `/etc/apache2/conf.d/userdata/ssl/2_4/<cpanel-user>/dot.example.com/gentle-dot.conf`. Change the port if you changed `DOT_PORT`.
+4. Rebuild and restart Apache:
+ ```bash
+ sudo /scripts/rebuildhttpdconf && sudo /scripts/restartsrv_httpd
+ ```
+
+### 5b. Plain VPS: Caddy in front
+
+```bash
+docker compose --profile caddy up -d
+```
+
+Caddy obtains the HTTPS certificate on its own and asks for the `DOT_USER` password.
+
+### 6. Open it
+
+Open `https://dot.example.com/#token=<your access key>`. The browser asks for the web server password first, then the page stores the access key and removes it from the address bar.
+
+## Update, back up, roll back
+
+```bash
+cd /opt/gentle-dot
+git pull --ff-only && docker compose up -d --build # update
+docker run --rm -v gentle-dot_dot-home:/data -v "$PWD":/backup busybox \
+ tar czf /backup/dot-home-$(date +%F).tgz -C /data . # back up the volume
+git checkout <previous-commit> && docker compose up -d --build # roll back
+```
+
+Never run `docker compose down -v`: `-v` deletes the volume with your conversations and memory.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| The page says the link is not valid | Wrong or old access key. Read it with `docker compose exec gentle-dot cat /home/dot/.gentle-dot/token`. |
+| The page loads but never connects | The proxy does not forward WebSockets (enable `mod_proxy_wstunnel`), or `DOT_DOMAIN` does not match the address you opened, so the Origin check refuses it. |
+| "The assistant is restarting" stays on | The agent cannot start; check `docker compose logs gentle-dot` for a missing model key or login. |
+
+## Video outline (about 2 minutes)
+
+1. "Gentle Dot runs on my Mac. Now let's put it on a HostGator VPS so I can use it from anywhere."
+2. Create the `dot` subdomain in DNS (step 1).
+3. `git clone` into `/opt/gentle-dot`, then create `.env` with the domain and the model key (steps 2–3).
+4. `docker compose up -d --build`, then `curl` the health check (step 4).
+5. In WHM: run AutoSSL, add the password file, and drop in the Apache include (step 5a).
+6. Open `https://dot.<domain>/#token=…` on a phone: same assistant, same memory.
+7. Close with the safety rules: HTTPS, two locks, an isolated container.