From ab4ffdb7e6dc03299179d601285563e6a4f51679 Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Wed, 20 May 2026 17:42:55 +0100
Subject: [PATCH 1/9] feat: cli

---
 pubky-docker.sh | 233 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 233 insertions(+)
 create mode 100755 pubky-docker.sh

diff --git a/pubky-docker.sh b/pubky-docker.sh
new file mode 100755
index 0000000..494c6ca
--- /dev/null
+++ b/pubky-docker.sh
@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_NAME="$(basename "$0")"
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+WORKSPACE_DIR="$(dirname "$SCRIPT_DIR")"
+
+BACKEND_ONLY=false
+
+readonly GITHUB_CHECK_REPO="https://github.com/pubky/pubky-core.git"
+
+usage() {
+  cat <<USAGE
+Usage: $SCRIPT_NAME [--backend-only] [--help]
+
+Clone the Pubky service repositories next to this directory, check out the
+selected refs, build the local Docker images, and start the Docker stack.
+
+Options:
+  --backend-only  Skip the franky frontend service.
+  --help          Show this help text.
+USAGE
+}
+
+log() {
+  printf '%s\n' "$*"
+}
+
+fail() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "Required command '$1' was not found."
+}
+
+parse_args() {
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --backend-only)
+        BACKEND_ONLY=true
+        ;;
+      --help|-h)
+        usage
+        exit 0
+        ;;
+      *)
+        fail "Unknown option: $1"
+        ;;
+    esac
+    shift
+  done
+}
+
+check_requirements() {
+  require_command git
+  require_command docker
+
+  if ! docker compose version >/dev/null 2>&1; then
+    fail "Docker Compose is not available. Install Docker with Compose v2 support."
+  fi
+}
+
+check_github_access() {
+  log "Checking GitHub clone access..."
+
+  if ! git ls-remote "$GITHUB_CHECK_REPO" HEAD >/dev/null 2>&1; then
+    fail "Could not access GitHub via git. Check your network connection and Git/GitHub configuration, then try again."
+  fi
+}
+
+copy_env_file() {
+  local env_sample="$SCRIPT_DIR/.env-sample"
+  local env_file="$SCRIPT_DIR/.env"
+
+  [ -f "$env_sample" ] || fail "Missing $env_sample."
+
+  if [ -f "$env_file" ]; then
+    log "Using existing .env."
+    return
+  fi
+
+  cp "$env_sample" "$env_file"
+  log "Created .env from .env-sample."
+}
+
+default_branch_for() {
+  local repo_url="$1"
+  local branch
+
+  branch="$(git ls-remote --symref "$repo_url" HEAD 2>/dev/null | sed -n 's#^ref: refs/heads/\([^[:space:]]*\)[[:space:]]*HEAD$#\1#p')"
+
+  if [ -z "$branch" ]; then
+    branch="main"
+  fi
+
+  printf '%s\n' "$branch"
+}
+
+prompt_ref() {
+  local name="$1"
+  local default_branch="$2"
+  local ref
+
+  printf 'Commit, tag, or branch for %s [%s]: ' "$name" "$default_branch" >&2
+  IFS= read -r ref || ref=""
+
+  if [ -z "$ref" ]; then
+    ref="$default_branch"
+  fi
+
+  printf '%s\n' "$ref"
+}
+
+ensure_clean_repo() {
+  local repo_dir="$1"
+  local status
+
+  status="$(git -C "$repo_dir" status --porcelain)"
+
+  if [ -n "$status" ]; then
+    fail "$repo_dir has local changes. Commit, stash, or clean them before changing refs."
+  fi
+}
+
+checkout_ref() {
+  local repo_dir="$1"
+  local ref="$2"
+
+  git -C "$repo_dir" fetch --tags origin
+
+  if git -C "$repo_dir" show-ref --verify --quiet "refs/remotes/origin/$ref"; then
+    git -C "$repo_dir" checkout --detach "origin/$ref"
+    return
+  fi
+
+  git -C "$repo_dir" checkout --detach "$ref"
+}
+
+clone_or_update_repo() {
+  local name="$1"
+  local repo_url="$2"
+  local target_dir="$3"
+  local ref="$4"
+
+  if [ -d "$target_dir/.git" ]; then
+    log "Updating $name in $target_dir..."
+    ensure_clean_repo "$target_dir"
+    checkout_ref "$target_dir" "$ref"
+    return
+  fi
+
+  if [ -e "$target_dir" ]; then
+    fail "$target_dir exists but is not a Git repository."
+  fi
+
+  log "Cloning $name into $target_dir..."
+  git clone "$repo_url" "$target_dir"
+  checkout_ref "$target_dir" "$ref"
+}
+
+print_repo_summary() {
+  local name="$1"
+  local target_dir="$2"
+  local commit
+
+  commit="$(git -C "$target_dir" rev-parse --short HEAD)"
+  log "Prepared $name at $commit."
+}
+
+prepare_repos() {
+  local repos=(
+    "pubky-nexus|https://github.com/pubky/pubky-nexus.git|pubky-nexus"
+    "pubky-core|https://github.com/pubky/pubky-core.git|pubky-core"
+    "homegate|https://github.com/pubky/homegate.git|homegate"
+  )
+
+  if [ "$BACKEND_ONLY" = false ]; then
+    repos+=("franky|https://github.com/pubky/pubky-app.git|franky")
+  fi
+
+  local entry
+  for entry in "${repos[@]}"; do
+    local name repo_url dir_name target_dir default_branch ref
+
+    IFS='|' read -r name repo_url dir_name <<EOF
+$entry
+EOF
+
+    target_dir="$WORKSPACE_DIR/$dir_name"
+    default_branch="$(default_branch_for "$repo_url")"
+    ref="$(prompt_ref "$name" "$default_branch")"
+
+    clone_or_update_repo "$name" "$repo_url" "$target_dir" "$ref"
+    print_repo_summary "$name" "$target_dir"
+  done
+}
+
+build_and_start_stack() {
+  local -a compose_base
+  local -a profiles
+  local -a services
+
+  compose_base=(docker compose --project-directory "$SCRIPT_DIR" --file "$SCRIPT_DIR/docker-compose.yml")
+  profiles=(--profile backend)
+  services=(homeserver nexusd homegate)
+
+  if [ "$BACKEND_ONLY" = false ]; then
+    profiles+=(--profile franky)
+    services+=(franky)
+  fi
+
+  log "Building local Pubky images..."
+  "${compose_base[@]}" "${profiles[@]}" build "${services[@]}"
+
+  log "Starting Docker stack..."
+  "${compose_base[@]}" "${profiles[@]}" up -d
+}
+
+main() {
+  parse_args "$@"
+  check_requirements
+  check_github_access
+  copy_env_file
+  prepare_repos
+  build_and_start_stack
+
+  log "Pubky Docker stack is running."
+}
+
+main "$@"

From e218d6ba179af8f1bf3df8df1e075a00043725fd Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Wed, 20 May 2026 20:16:13 +0100
Subject: [PATCH 2/9] feat: track last built ref

---
 pubky-docker.sh | 104 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 92 insertions(+), 12 deletions(-)

diff --git a/pubky-docker.sh b/pubky-docker.sh
index 494c6ca..2381521 100755
--- a/pubky-docker.sh
+++ b/pubky-docker.sh
@@ -7,8 +7,11 @@ SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
 WORKSPACE_DIR="$(dirname "$SCRIPT_DIR")"
 
 BACKEND_ONLY=false
+BUILD_SERVICES=()
+PREPARED_COMMITS=()
 
 readonly GITHUB_CHECK_REPO="https://github.com/pubky/pubky-core.git"
+readonly BUILD_STATE_FILE="$SCRIPT_DIR/.build-state"
 
 usage() {
   cat <<USAGE
@@ -170,22 +173,95 @@ print_repo_summary() {
   log "Prepared $name at $commit."
 }
 
+previous_built_commit() {
+  local service="$1"
+  local existing_service
+  local existing_commit
+
+  [ -f "$BUILD_STATE_FILE" ] || return 0
+
+  while read -r existing_service existing_commit; do
+    if [ "$existing_service" = "$service" ]; then
+      printf '%s\n' "$existing_commit"
+      return 0
+    fi
+  done < "$BUILD_STATE_FILE"
+
+  return 0
+}
+
+mark_service_for_build_if_needed() {
+  local service="$1"
+  local commit="$2"
+  local previous_commit
+
+  PREPARED_COMMITS+=("$service|$commit")
+  previous_commit="$(previous_built_commit "$service")"
+
+  if [ "$previous_commit" = "$commit" ]; then
+    log "Source unchanged for $service; skipping image build."
+    return
+  fi
+
+  BUILD_SERVICES+=("$service")
+}
+
+record_built_commit() {
+  local service="$1"
+  local commit="$2"
+  local state_dir
+  local temp_file
+  local existing_service
+  local existing_commit
+
+  state_dir="$(dirname "$BUILD_STATE_FILE")"
+  temp_file="$BUILD_STATE_FILE.tmp"
+
+  mkdir -p "$state_dir"
+
+  if [ -f "$BUILD_STATE_FILE" ]; then
+    while read -r existing_service existing_commit; do
+      [ -n "$existing_service" ] || continue
+      [ "$existing_service" != "$service" ] || continue
+      printf '%s %s\n' "$existing_service" "$existing_commit"
+    done < "$BUILD_STATE_FILE" > "$temp_file"
+  else
+    : > "$temp_file"
+  fi
+
+  printf '%s %s\n' "$service" "$commit" >> "$temp_file"
+  mv "$temp_file" "$BUILD_STATE_FILE"
+}
+
+record_built_commits() {
+  local entry
+  local service
+  local commit
+
+  for entry in "${PREPARED_COMMITS[@]}"; do
+    IFS='|' read -r service commit <<EOF
+$entry
+EOF
+    record_built_commit "$service" "$commit"
+  done
+}
+
 prepare_repos() {
   local repos=(
-    "pubky-nexus|https://github.com/pubky/pubky-nexus.git|pubky-nexus"
-    "pubky-core|https://github.com/pubky/pubky-core.git|pubky-core"
-    "homegate|https://github.com/pubky/homegate.git|homegate"
+    "pubky-nexus|https://github.com/pubky/pubky-nexus.git|pubky-nexus|nexusd"
+    "pubky-core|https://github.com/pubky/pubky-core.git|pubky-core|homeserver"
+    "homegate|https://github.com/pubky/homegate.git|homegate|homegate"
   )
 
   if [ "$BACKEND_ONLY" = false ]; then
-    repos+=("franky|https://github.com/pubky/pubky-app.git|franky")
+    repos+=("franky|https://github.com/pubky/pubky-app.git|franky|franky")
   fi
 
   local entry
   for entry in "${repos[@]}"; do
-    local name repo_url dir_name target_dir default_branch ref
+    local name repo_url dir_name service target_dir default_branch ref commit
 
-    IFS='|' read -r name repo_url dir_name <<EOF
+    IFS='|' read -r name repo_url dir_name service <<EOF
 $entry
 EOF
 
@@ -195,28 +271,32 @@ EOF
 
     clone_or_update_repo "$name" "$repo_url" "$target_dir" "$ref"
     print_repo_summary "$name" "$target_dir"
+    commit="$(git -C "$target_dir" rev-parse HEAD)"
+    mark_service_for_build_if_needed "$service" "$commit"
   done
 }
 
 build_and_start_stack() {
   local -a compose_base
   local -a profiles
-  local -a services
 
   compose_base=(docker compose --project-directory "$SCRIPT_DIR" --file "$SCRIPT_DIR/docker-compose.yml")
   profiles=(--profile backend)
-  services=(homeserver nexusd homegate)
 
   if [ "$BACKEND_ONLY" = false ]; then
     profiles+=(--profile franky)
-    services+=(franky)
   fi
 
-  log "Building local Pubky images..."
-  "${compose_base[@]}" "${profiles[@]}" build "${services[@]}"
+  if [ "${#BUILD_SERVICES[@]}" -gt 0 ]; then
+    log "Building changed Pubky images: ${BUILD_SERVICES[*]}"
+    "${compose_base[@]}" "${profiles[@]}" build "${BUILD_SERVICES[@]}"
+    record_built_commits
+  else
+    log "No Pubky source changes detected; skipping image build."
+  fi
 
   log "Starting Docker stack..."
-  "${compose_base[@]}" "${profiles[@]}" up -d
+  "${compose_base[@]}" "${profiles[@]}" up
 }
 
 main() {

From d96b2709e8d7d388feb300286389737aae8f7045 Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Wed, 20 May 2026 21:54:40 +0100
Subject: [PATCH 3/9] feat: add initial prompt to skip build prompts

---
 pubky-docker.sh | 84 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 81 insertions(+), 3 deletions(-)

diff --git a/pubky-docker.sh b/pubky-docker.sh
index 2381521..e083f3f 100755
--- a/pubky-docker.sh
+++ b/pubky-docker.sh
@@ -173,6 +173,16 @@ print_repo_summary() {
   log "Prepared $name at $commit."
 }
 
+required_services() {
+  local services=(homeserver nexusd homegate)
+
+  if [ "$BACKEND_ONLY" = false ]; then
+    services+=(franky)
+  fi
+
+  printf '%s\n' "${services[@]}"
+}
+
 previous_built_commit() {
   local service="$1"
   local existing_service
@@ -190,6 +200,53 @@ previous_built_commit() {
   return 0
 }
 
+build_state_is_complete() {
+  local service
+  local commit
+
+  [ -f "$BUILD_STATE_FILE" ] || return 1
+
+  while IFS= read -r service; do
+    commit="$(previous_built_commit "$service")"
+    [ -n "$commit" ] || return 1
+  done < <(required_services)
+}
+
+print_build_state() {
+  local service
+  local commit
+  local short_commit
+
+  log "Existing build state ($BUILD_STATE_FILE):"
+
+  while IFS= read -r service; do
+    commit="$(previous_built_commit "$service")"
+    short_commit="${commit:0:12}"
+    log "  $service: $short_commit"
+  done < <(required_services)
+}
+
+maybe_offer_resume_prompt() {
+  local choice
+
+  build_state_is_complete || return 1
+
+  print_build_state
+  printf '\n[u] Start stack now  [p] Proceed to select refs: ' >&2
+  IFS= read -r choice || choice=""
+
+  choice="$(printf '%s' "$choice" | tr '[:upper:]' '[:lower:]')"
+
+  case "$choice" in
+    p|proceed)
+      return 1
+      ;;
+    *)
+      return 0
+      ;;
+  esac
+}
+
 mark_service_for_build_if_needed() {
   local service="$1"
   local commit="$2"
@@ -276,6 +333,21 @@ EOF
   done
 }
 
+start_stack() {
+  local -a compose_base
+  local -a profiles
+
+  compose_base=(docker compose --project-directory "$SCRIPT_DIR" --file "$SCRIPT_DIR/docker-compose.yml")
+  profiles=(--profile backend)
+
+  if [ "$BACKEND_ONLY" = false ]; then
+    profiles+=(--profile franky)
+  fi
+
+  log "Starting Docker stack..."
+  "${compose_base[@]}" "${profiles[@]}" up
+}
+
 build_and_start_stack() {
   local -a compose_base
   local -a profiles
@@ -295,15 +367,21 @@ build_and_start_stack() {
     log "No Pubky source changes detected; skipping image build."
   fi
 
-  log "Starting Docker stack..."
-  "${compose_base[@]}" "${profiles[@]}" up
+  start_stack
 }
 
 main() {
   parse_args "$@"
   check_requirements
-  check_github_access
   copy_env_file
+
+  if maybe_offer_resume_prompt; then
+    start_stack
+    log "Pubky Docker stack is running."
+    return
+  fi
+
+  check_github_access
   prepare_repos
   build_and_start_stack
 

From 0e790bce4c928eccd0d7f6b93f4154263623d30b Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Wed, 20 May 2026 22:09:39 +0100
Subject: [PATCH 4/9] chore: refactor

---
 pubky-docker.sh | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/pubky-docker.sh b/pubky-docker.sh
index e083f3f..cec921b 100755
--- a/pubky-docker.sh
+++ b/pubky-docker.sh
@@ -305,24 +305,24 @@ EOF
 
 prepare_repos() {
   local repos=(
-    "pubky-nexus|https://github.com/pubky/pubky-nexus.git|pubky-nexus|nexusd"
-    "pubky-core|https://github.com/pubky/pubky-core.git|pubky-core|homeserver"
-    "homegate|https://github.com/pubky/homegate.git|homegate|homegate"
+    "pubky-nexus|https://github.com/pubky/pubky-nexus.git|nexusd"
+    "pubky-core|https://github.com/pubky/pubky-core.git|homeserver"
+    "homegate|https://github.com/pubky/homegate.git|homegate"
   )
 
   if [ "$BACKEND_ONLY" = false ]; then
-    repos+=("franky|https://github.com/pubky/pubky-app.git|franky|franky")
+    repos+=("franky|https://github.com/pubky/pubky-app.git|franky")
   fi
 
   local entry
   for entry in "${repos[@]}"; do
-    local name repo_url dir_name service target_dir default_branch ref commit
+    local name repo_url service target_dir default_branch ref commit
 
-    IFS='|' read -r name repo_url dir_name service <<EOF
+    IFS='|' read -r name repo_url service <<EOF
 $entry
 EOF
 
-    target_dir="$WORKSPACE_DIR/$dir_name"
+    target_dir="$WORKSPACE_DIR/$name"
     default_branch="$(default_branch_for "$repo_url")"
     ref="$(prompt_ref "$name" "$default_branch")"
 

From be2f93f78d894bd9a9f5e00b1472c8cf18d53d7a Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Wed, 20 May 2026 22:19:34 +0100
Subject: [PATCH 5/9] chore: refactor

---
 pubky-docker.sh | 28 +++++-----------------------
 1 file changed, 5 insertions(+), 23 deletions(-)

diff --git a/pubky-docker.sh b/pubky-docker.sh
index cec921b..ce85e88 100755
--- a/pubky-docker.sh
+++ b/pubky-docker.sh
@@ -333,21 +333,6 @@ EOF
   done
 }
 
-start_stack() {
-  local -a compose_base
-  local -a profiles
-
-  compose_base=(docker compose --project-directory "$SCRIPT_DIR" --file "$SCRIPT_DIR/docker-compose.yml")
-  profiles=(--profile backend)
-
-  if [ "$BACKEND_ONLY" = false ]; then
-    profiles+=(--profile franky)
-  fi
-
-  log "Starting Docker stack..."
-  "${compose_base[@]}" "${profiles[@]}" up
-}
-
 build_and_start_stack() {
   local -a compose_base
   local -a profiles
@@ -367,7 +352,8 @@ build_and_start_stack() {
     log "No Pubky source changes detected; skipping image build."
   fi
 
-  start_stack
+  log "Starting Docker stack..."
+  "${compose_base[@]}" "${profiles[@]}" up
 }
 
 main() {
@@ -375,16 +361,12 @@ main() {
   check_requirements
   copy_env_file
 
-  if maybe_offer_resume_prompt; then
-    start_stack
-    log "Pubky Docker stack is running."
-    return
+  if ! maybe_offer_resume_prompt; then
+    check_github_access
+    prepare_repos
   fi
 
-  check_github_access
-  prepare_repos
   build_and_start_stack
-
   log "Pubky Docker stack is running."
 }
 

From 7b00392dcef47ee36fcaf25a77a3a5d433bc7704 Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Thu, 21 May 2026 10:30:48 +0100
Subject: [PATCH 6/9] chore: refactor to use 'pubky-app' instead of 'franky'

---
 .env-sample        |   8 ++--
 Readme.md          | 112 ++++++++++++++++++++-------------------------
 docker-compose.yml |  13 +++---
 pubky-docker.sh    |   8 ++--
 4 files changed, 65 insertions(+), 76 deletions(-)

diff --git a/.env-sample b/.env-sample
index 8bbcca5..fdef042 100644
--- a/.env-sample
+++ b/.env-sample
@@ -3,7 +3,7 @@
 #####
 
 # Full stack on `docker compose up`; use `docker compose --profile backend up` for backend only
-COMPOSE_PROFILES=backend,franky
+COMPOSE_PROFILES=backend,pubky-app
 
 # mainnet or testnet network
 NETWORK=testnet # mainnet
@@ -21,7 +21,7 @@ POSTGRES_DB=pubky_homeserver
 
 # # Testnet
 NEXT_PUBLIC_HOMESERVER=8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo
-NEXT_PUBLIC_NEXUS=http://localhost:8080
+NEXT_PUBLIC_NEXUS_URL=http://localhost:8080
 NEXT_PUBLIC_TESTNET=true
 NEXT_PUBLIC_DEFAULT_HTTP_RELAY=http://localhost:15412/link/
 NEXT_PUBLIC_PKARR_RELAYS=["https://pkarr.pubky.app","https://pkarr.pubky.org"] # Ignored when using Testnet
@@ -30,10 +30,10 @@ NEXT_ENABLE_PLAUSIBLE=false
 
 # Mainnet
 # NEXT_PUBLIC_HOMESERVER=8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo
-# NEXT_PUBLIC_NEXUS=http://localhost:8080
+# NEXT_PUBLIC_NEXUS_URL=http://localhost:8080
 # NEXT_PUBLIC_TESTNET=false
 # NEXT_PUBLIC_DEFAULT_HTTP_RELAY=https://httprelay.staging.pubky.app/link/
 
 # # Replace with these for mainnet Staging servers
 # NEXT_PUBLIC_HOMESERVER=ufibwbmed6jeq9k4p583go95wofakh9fwpp4k734trq79pd9u1uy
-# NEXT_PUBLIC_NEXUS=https://nexus.staging.pubky.app
+# NEXT_PUBLIC_NEXUS_URL=https://nexus.staging.pubky.app
diff --git a/Readme.md b/Readme.md
index 027d1ac..178a0d8 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,93 +1,81 @@
-# 💻 Pubky Docker
+# Pubky Docker
 
-One click setup to run locally an example full Pubky Social (App) stack. This orchestration will run:
+Run a local Pubky stack from source. The Pubky service images are built from local Git checkouts rather than pulled from the Docker registry, because the registry images are not currently the source of truth for local development.
 
-- [Pkarr relay](https://github.com/pubky/pkarr):
-- [Pubky Homeserver](https://github.com/pubky/pubky-core/tree/main/pubky-homeserver): Instance of pubky decentralized data storage.
-- [Pubky Nexus](https://github.com/pubky/pubky-nexus): aggregator and indexer of `/pub/pubky.app` data that creates a powerful social-media-like API
-- [Pubky App](https://github.com/pubky/pubky-app): client for the pubky social media app.
+This orchestration can run:
 
-## ⚠️ Warning
+- [Pubky Homeserver](https://github.com/pubky/pubky-core/tree/main/pubky-homeserver), from `pubky/pubky-core`
+- [Pubky Nexus](https://github.com/pubky/pubky-nexus), from `pubky/pubky-nexus`
+- [Homegate](https://github.com/pubky/homegate), from `pubky/homegate`
+- [Pubky App](https://github.com/pubky/pubky-app), run as the `pubky-app` Compose service
 
-Running the full stack is overkill if your goal is only to develop an application using Pubky.
+Third-party infrastructure images such as Postgres, Neo4j, Redis, Redis Insight, and WireMock may still be pulled by Docker.
 
-For application development, use the official client libraries instead:
+## Quick Start
 
-- JavaScript: https://www.npmjs.com/package/@synonymdev/pubky
-- Rust: https://crates.io/crates/pubky
+Run the setup script from this directory:
 
-Only run this full orchestration if you're specifically experimenting with the complete stack with interest on the Nexus indexer and the social frontend client.
-
-## Using public docker images
-
-All images are stored in public [registry](https://hub.docker.com/u/synonymsoft) and by default the `latest` tag is used.
-
-The image tag and registry are environment variables, so if needed they could be changed
-
-```
-REGISTRY - registry by default synonymsoft
-PUBKY_APP_TAG - tag for pubky-app/client by default latest
-PUBKY_NEXUS_TAG - tag for pubky-nexus by default latest
-HOMESERVER_TAG - tag for homeserver by default latest
-PKARR_TAG - tag for pkarr by default latest
-```
-
-Make a copy of `.env-sample` into `.env` and set your preferences for `mainnet` or `testnet`.
-
-Run:
-
-```
-docker compose up -d
+```bash
+./pubky-docker.sh
 ```
 
-## Building from scratch
+The script will:
 
-### ⚙️ Setup
+- Check that `git`, Docker, and Docker Compose are available.
+- Check that Git can read from GitHub before attempting clones.
+- Copy `.env-sample` to `.env` if `.env` does not already exist.
+- Ask for a commit, tag, or branch for each service. Press Enter to use the head of the repository's default branch.
+- Clone or update the service repositories next to this directory.
+- Build local Docker images for Pubky services whose checked-out source commit changed.
+- Start the stack with Docker Compose.
 
-This setup builds directly from the `pubky/pkarr`, `pubky/pubky-core`, `pubky/pubky-nexus`, and `pubky/pubky-app` repositories.
+The directory containing this project can be named `pubky-docker`, `docker`, or anything else. Repositories are cloned beside that directory.
 
-Make a copy of `.env-sample` into `.env` and set your preferences for `mainnet` or `testnet`.
+## Backend Only
 
-To run entire stack:
-```bash
-docker compose up
-```
+If you want to run your own frontend separately, skip the `pubky-app` service:
 
-To run without pubky-app client:
 ```bash
-docker compose --profile backend up
+./pubky-docker.sh --backend-only
 ```
 
-### 📁 Directory Structure Requirement
+This still clones, builds, and runs the backend services: `pubky-core`, `pubky-nexus`, and `homegate`.
 
-Before running `docker compose up`, ensure the following four repositories are cloned **at the same directory level** as `pubky-docker`. This is necessary because the Docker setup references them via relative paths.
+## Directory Layout
 
-Your directory should look like this:
+After running the script, your workspace will look similar to this:
 
-```
+```text
 your_working_directory/
-├── pubky-docker/ # this project!
-├── pkarr/
+├── pubky-docker/
 ├── pubky-core/
 ├── pubky-nexus/
-├── pubky-app/
+├── homegate/
+└── pubky-app/
 ```
 
-Clone each required repository:
+## Re-running With Different Refs
 
+Run the script again and enter new refs when prompted:
+
+```bash
+./pubky-docker.sh
 ```
-git clone https://github.com/pubky/pubky-docker.git # this repository
-git clone https://github.com/pubky/pkarr.git
-git clone https://github.com/pubky/pubky-core.git
-git clone https://github.com/pubky/pubky-nexus.git
-git clone https://github.com/pubky/pubky-app.git
-```
 
-Then navigate into `pubky-docker`, configure your `.env`, and run:
+For existing repositories, the script refuses to change refs if there are local changes. Commit, stash, or clean those changes first, then rerun the script.
+
+The script records the last built commit for each Compose service in `.storage/pubky-docker-builds`. On subsequent runs, services at the same commit skip the explicit image build step.
 
+## Manual Compose Commands
+
+The script is the recommended path, but the Compose profiles can also be used directly after repositories have been prepared:
+
+```bash
+docker compose --profile backend --profile pubky-app up -d
 ```
-cd pubky-docker
-cp .env-sample .env
-# edit .env to choose between mainnet or testnet
-docker compose up
+
+For backend only:
+
+```bash
+docker compose --profile backend up -d
 ```
diff --git a/docker-compose.yml b/docker-compose.yml
index 14af3ec..1f4807e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -126,13 +126,13 @@ services:
       - nexus-redis
     restart: always
 
-  # 4. Franky Social UI
-  franky:
-    profiles: [franky]
-    container_name: franky
-    image: "${REGISTRY:-synonymsoft}/franky-${NETWORK:-testnet}:${FRANKY_TAG:-latest}"
+  # 4. Pubky App Social UI
+  pubky-app:
+    profiles: [pubky-app]
+    container_name: pubky-app
+    image: "${REGISTRY:-synonymsoft}/pubky-app-${NETWORK:-testnet}:${PUBKY_APP_TAG:-latest}"
     build:
-      context: ../franky
+      context: ../pubky-app
       args:
         NEXT_PUBLIC_DB_VERSION: ${NEXT_PUBLIC_DB_VERSION:-2}
         NEXT_PUBLIC_DB_NAME: ${NEXT_PUBLIC_DB_NAME:-franky}
@@ -163,6 +163,7 @@ services:
         NEXT_PUBLIC_HOMEGATE_URL: ${NEXT_PUBLIC_HOMEGATE_URL:-http://localhost:6300}
         NEXT_PUBLIC_MODERATION_ID: ${NEXT_PUBLIC_MODERATION_ID:-euwmq57zefw5ynnkhh37b3gcmhs7g3cptdbw1doaxj1pbmzp3wro}
         NEXT_PUBLIC_MODERATED_TAGS: ${NEXT_PUBLIC_MODERATED_TAGS:-["nudity"]}
+        NEXT_ENABLE_PLAUSIBLE: ${NEXT_ENABLE_PLAUSIBLE:-false}
         BASE_URL_SUPPORT: ${BASE_URL_SUPPORT:-https://support.pubky.app}
         SUPPORT_API_ACCESS_TOKEN: ${SUPPORT_API_ACCESS_TOKEN:-test-token}
         SUPPORT_ACCOUNT_ID: ${SUPPORT_ACCOUNT_ID:-1}
diff --git a/pubky-docker.sh b/pubky-docker.sh
index ce85e88..b3af4dd 100755
--- a/pubky-docker.sh
+++ b/pubky-docker.sh
@@ -21,7 +21,7 @@ Clone the Pubky service repositories next to this directory, check out the
 selected refs, build the local Docker images, and start the Docker stack.
 
 Options:
-  --backend-only  Skip the franky frontend service.
+  --backend-only  Skip the pubky-app frontend service.
   --help          Show this help text.
 USAGE
 }
@@ -177,7 +177,7 @@ required_services() {
   local services=(homeserver nexusd homegate)
 
   if [ "$BACKEND_ONLY" = false ]; then
-    services+=(franky)
+    services+=(pubky-app)
   fi
 
   printf '%s\n' "${services[@]}"
@@ -311,7 +311,7 @@ prepare_repos() {
   )
 
   if [ "$BACKEND_ONLY" = false ]; then
-    repos+=("franky|https://github.com/pubky/pubky-app.git|franky")
+    repos+=("pubky-app|https://github.com/pubky/pubky-app.git|pubky-app")
   fi
 
   local entry
@@ -341,7 +341,7 @@ build_and_start_stack() {
   profiles=(--profile backend)
 
   if [ "$BACKEND_ONLY" = false ]; then
-    profiles+=(--profile franky)
+    profiles+=(--profile pubky-app)
   fi
 
   if [ "${#BUILD_SERVICES[@]}" -gt 0 ]; then

From 9a00e1eca334558df3d4e1ee2305227d68276438 Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Thu, 21 May 2026 10:39:32 +0100
Subject: [PATCH 7/9] chore: update readme to cover cli and public repo

---
 Readme.md | 82 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 63 insertions(+), 19 deletions(-)

diff --git a/Readme.md b/Readme.md
index 178a0d8..ebbe053 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,19 +1,28 @@
 # Pubky Docker
 
-Run a local Pubky stack from source. The Pubky service images are built from local Git checkouts rather than pulled from the Docker registry, because the registry images are not currently the source of truth for local development.
-
-This orchestration can run:
+One-click setup to run a local Pubky Social stack. This orchestration can run:
 
 - [Pubky Homeserver](https://github.com/pubky/pubky-core/tree/main/pubky-homeserver), from `pubky/pubky-core`
 - [Pubky Nexus](https://github.com/pubky/pubky-nexus), from `pubky/pubky-nexus`
 - [Homegate](https://github.com/pubky/homegate), from `pubky/homegate`
-- [Pubky App](https://github.com/pubky/pubky-app), run as the `pubky-app` Compose service
+- [Pubky App](https://github.com/pubky/pubky-app), as the `pubky-app` Compose service
+
+Third-party infrastructure images (Postgres, Neo4j, Redis, Redis Insight, WireMock) are pulled from their public registries.
+
+## Warning
+
+Running the full stack is overkill if your goal is only to develop an application using Pubky. For application development, use the official client libraries instead:
 
-Third-party infrastructure images such as Postgres, Neo4j, Redis, Redis Insight, and WireMock may still be pulled by Docker.
+- JavaScript: https://www.npmjs.com/package/@synonymdev/pubky
+- Rust: https://crates.io/crates/pubky
 
-## Quick Start
+Only run this full orchestration if you are experimenting with the complete stack, especially the Nexus indexer and the social frontend.
 
-Run the setup script from this directory:
+## Local Setup From Source (Recommended)
+
+For contributors and local development, use `pubky-docker.sh`. It clones the service repositories, checks out the refs you choose, builds Pubky images from source, and starts the stack. The public Docker registry is not used for Pubky services on this path.
+
+Run the script from this directory:
 
 ```bash
 ./pubky-docker.sh
@@ -24,24 +33,25 @@ The script will:
 - Check that `git`, Docker, and Docker Compose are available.
 - Check that Git can read from GitHub before attempting clones.
 - Copy `.env-sample` to `.env` if `.env` does not already exist.
+- If `.build-state` has a complete record for the selected services, list those commits and offer to start the stack immediately or proceed to ref selection.
 - Ask for a commit, tag, or branch for each service. Press Enter to use the head of the repository's default branch.
 - Clone or update the service repositories next to this directory.
-- Build local Docker images for Pubky services whose checked-out source commit changed.
+- Build local Docker images only for services whose checked-out commit changed.
 - Start the stack with Docker Compose.
 
 The directory containing this project can be named `pubky-docker`, `docker`, or anything else. Repositories are cloned beside that directory.
 
-## Backend Only
+### Backend Only
 
-If you want to run your own frontend separately, skip the `pubky-app` service:
+If you want to run your own frontend separately:
 
 ```bash
 ./pubky-docker.sh --backend-only
 ```
 
-This still clones, builds, and runs the backend services: `pubky-core`, `pubky-nexus`, and `homegate`.
+This still clones, builds, and runs `pubky-core`, `pubky-nexus`, and `homegate`.
 
-## Directory Layout
+### Directory Layout
 
 After running the script, your workspace will look similar to this:
 
@@ -54,27 +64,61 @@ your_working_directory/
 └── pubky-app/
 ```
 
-## Re-running With Different Refs
+### Re-running
 
-Run the script again and enter new refs when prompted:
+Run the script again to pick new refs:
 
 ```bash
 ./pubky-docker.sh
 ```
 
-For existing repositories, the script refuses to change refs if there are local changes. Commit, stash, or clean those changes first, then rerun the script.
+For existing repositories, the script refuses to change refs if there are local changes. Commit, stash, or clean those changes first, then rerun.
+
+The script records the last built commit per Compose service in `.build-state`. On later runs, unchanged services skip the image build step. If `.build-state` is complete for your selected profile set, you can start the stack without going through ref selection again.
+
+## Using Public Docker Images
+
+All Pubky service images are published on the public [Synonymsoft registry](https://hub.docker.com/u/synonymsoft). By default, Compose uses the `latest` tag.
+
+Image tags and registry can be overridden in `.env`:
+
+```text
+REGISTRY          # default: synonymsoft
+HOMESERVER_TAG    # default: latest
+PUBKY_NEXUS_TAG   # default: latest
+PUBKY_APP_TAG     # default: latest
+HOMEGATE_TAG      # default: latest
+```
+
+Copy `.env-sample` to `.env` and set your preferences for `mainnet` or `testnet`:
+
+```bash
+cp .env-sample .env
+```
+
+Start the full stack (profiles are set via `COMPOSE_PROFILES` in `.env`):
+
+```bash
+docker compose up -d
+```
+
+Backend only:
+
+```bash
+docker compose --profile backend up -d
+```
 
-The script records the last built commit for each Compose service in `.storage/pubky-docker-builds`. On subsequent runs, services at the same commit skip the explicit image build step.
+This path does not clone or build service repositories. You only need the compose files from this project and a configured `.env`.
 
-## Manual Compose Commands
+## Manual Compose (After Preparing Repositories)
 
-The script is the recommended path, but the Compose profiles can also be used directly after repositories have been prepared:
+If you have already cloned the service repositories and checked out refs yourself, you can use Compose directly:
 
 ```bash
 docker compose --profile backend --profile pubky-app up -d
 ```
 
-For backend only:
+Backend only:
 
 ```bash
 docker compose --profile backend up -d

From 9358ab13d443e0e932457d23b8099f39f858b4db Mon Sep 17 00:00:00 2001
From: James Browning <jamesbrowning91@gmail.com>
Date: Thu, 21 May 2026 11:21:19 +0100
Subject: [PATCH 8/9] chore: refactor and rename

---
 Readme.md                              | 8 ++++----
 pubky-docker.sh => pubky-docker-cli.sh | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)
 rename pubky-docker.sh => pubky-docker-cli.sh (98%)

diff --git a/Readme.md b/Readme.md
index ebbe053..b5c864a 100644
--- a/Readme.md
+++ b/Readme.md
@@ -20,12 +20,12 @@ Only run this full orchestration if you are experimenting with the complete stac
 
 ## Local Setup From Source (Recommended)
 
-For contributors and local development, use `pubky-docker.sh`. It clones the service repositories, checks out the refs you choose, builds Pubky images from source, and starts the stack. The public Docker registry is not used for Pubky services on this path.
+For contributors and local development, use `pubky-docker-cli.sh`. It clones the service repositories, checks out the refs you choose, builds Pubky images from source, and starts the stack. The public Docker registry is not used for Pubky services on this path.
 
 Run the script from this directory:
 
 ```bash
-./pubky-docker.sh
+./pubky-docker-cli.sh
 ```
 
 The script will:
@@ -46,7 +46,7 @@ The directory containing this project can be named `pubky-docker`, `docker`, or
 If you want to run your own frontend separately:
 
 ```bash
-./pubky-docker.sh --backend-only
+./pubky-docker-cli.sh --backend-only
 ```
 
 This still clones, builds, and runs `pubky-core`, `pubky-nexus`, and `homegate`.
@@ -69,7 +69,7 @@ your_working_directory/
 Run the script again to pick new refs:
 
 ```bash
-./pubky-docker.sh
+./pubky-docker-cli.sh
 ```
 
 For existing repositories, the script refuses to change refs if there are local changes. Commit, stash, or clean those changes first, then rerun.
diff --git a/pubky-docker.sh b/pubky-docker-cli.sh
similarity index 98%
rename from pubky-docker.sh
rename to pubky-docker-cli.sh
index b3af4dd..b9bed63 100755
--- a/pubky-docker.sh
+++ b/pubky-docker-cli.sh
@@ -232,13 +232,13 @@ maybe_offer_resume_prompt() {
   build_state_is_complete || return 1
 
   print_build_state
-  printf '\n[u] Start stack now  [p] Proceed to select refs: ' >&2
+  printf '\n[s] Start stack now  [c] Choose refs: ' >&2
   IFS= read -r choice || choice=""
 
   choice="$(printf '%s' "$choice" | tr '[:upper:]' '[:lower:]')"
 
   case "$choice" in
-    p|proceed)
+    c|choose)
       return 1
       ;;
     *)

From 9d07401059d0ab9900cebd3d022dd0a526a4dfb2 Mon Sep 17 00:00:00 2001
From: jazkamer <v.rodionov@protonmail.com>
Date: Fri, 29 May 2026 17:35:34 +0300
Subject: [PATCH 9/9] fix: update homeserver image name and config

---
 docker-compose.yml     | 2 +-
 homeserver.config.toml | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 1f4807e..1d47358 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -24,7 +24,7 @@ services:
   homeserver:
     profiles: [backend]
     container_name: homeserver
-    image: "${REGISTRY:-synonymsoft}/homeserver:${HOMESERVER_TAG:-latest}"
+    image: "${REGISTRY:-synonymsoft}/homeserver-${HOMESERVER_ENV:-testnet}:${HOMESERVER_TAG:-latest}"
     restart: always
     build:
       context: ../pubky-core
diff --git a/homeserver.config.toml b/homeserver.config.toml
index 6759524..a2451be 100644
--- a/homeserver.config.toml
+++ b/homeserver.config.toml
@@ -11,3 +11,8 @@ public_ip = "172.18.0.4"
 
 [derive]
 testnet_host = "homeserver"
+
+[admin]
+enabled = true
+listen_socket = "0.0.0.0:6288"
+admin_password = "admin"