docs(docker): fix GPG keyring compatibility and improve documentation

- Use ~/.cryptic-gpg instead of ~/.gnupg to avoid keyboxd daemon
  conflicts on modern macOS/Linux (GPG 2.4+)
- Add two methods for running client: env vars vs command-line flags
- Document build context requirement (parent directory with cryptic-tui)
- Add troubleshooting for common COPY failed build errors
- Simplify server setup with dedicated ~/.cryptic_server directory
- Remove redundant admin bootstrap section (covered in quick start)

Also fix entrypoint script to execute custom commands directly without
banner output, improving onboarding and console mode usability.

Author: etnt

docs/DOCKER.md

@@ -8,36 +8,51 @@ This guide explains how to deploy the Cryptic client and or the
 
 **Run the latest client image:**
 
-[Demo](https://youtu.be/acNHqzHia3o?si=_4mQuE4KQooxb1UM)
+[Video Demo](https://youtu.be/acNHqzHia3o?si=_4mQuE4KQooxb1UM)
 
 ```bash
 # Get the latest Client docker image
 docker pull ghcr.io/etnt/cryptic-tui:latest
 
+# Create a separate GPG directory for Docker (avoids conflicts with host's keyboxd)
+mkdir -p ~/.cryptic-gpg
+
 # Run the Cryptic Onboarding script
-#  1. Generate a GPG key pair (or use existing one from ~/.gnupg)
+#  1. Generate a GPG key pair (stored in ~/.cryptic-gpg on host)
 #  2. Export the generated key
 #  3. Send the key and fingerprint to the admin
-#  4. WAIT! - Do not exit the onboard script (the container will be gone) 
+#  4. WAIT! - Do not exit the onboard script until certificate is received
 #  5. When admin has registered your key: Request a TLS certificate from server
 #    If your server is running on localhost on your Host machine, specify:
 #    cryptic-server as your server address (see the: `--add-host` below)
 #  6. Exit the onboard script
 # You should now see your certificates at ~/.cryptic/<user>/cryptic-server_<port>
 #
-# NOTE: ~/.gnupg is mounted so your GPG keyring is shared with the container.
-#       This is required for automatic certificate renewal.
+# NOTE: We use ~/.cryptic-gpg instead of ~/.gnupg because modern macOS/Linux
+#       GPG uses keyboxd daemon which doesn't work across container boundaries.
+#       The container manages its own GPG keyring that persists on the host.
 docker run -it --rm --name cryptic-client \
            -v ~/.cryptic:/home/cryptic/.cryptic \
-           -v ~/.gnupg:/home/cryptic/.gnupg \
+           -v ~/.cryptic-gpg:/home/cryptic/.gnupg \
            --add-host=cryptic-server:host-gateway \
            ghcr.io/etnt/cryptic-tui:latest sh -c 'cryptic --onboard'
 
 # Start the Cryptic client with your username (e.g `franz`)
 # You'll be prompted for a Passphrase which is used to encrypt your local DB
+
+# Method 1: Using environment variables
+docker run -it --rm --name cryptic-client \
+           -v ~/.cryptic:/home/cryptic/.cryptic \
+           -v ~/.cryptic-gpg:/home/cryptic/.gnupg \
+           --add-host=cryptic-server:host-gateway \
+           -e CRYPTIC_USERNAME=franz \
+           -e CRYPTIC_ENABLE_DB=true \
+           ghcr.io/etnt/cryptic-tui:latest
+
+# Method 2: Using command-line flags 
 docker run -it --rm --name cryptic-client \
            -v ~/.cryptic:/home/cryptic/.cryptic \
-           -v ~/.gnupg:/home/cryptic/.gnupg \
+           -v ~/.cryptic-gpg:/home/cryptic/.gnupg \
            --add-host=cryptic-server:host-gateway \
            ghcr.io/etnt/cryptic-tui:latest sh -c 'cryptic -u franz --enable-db --tui'
 ```
@@ -48,6 +63,10 @@ docker run -it --rm --name cryptic-client \
 # Get the latest Server docker image
 docker pull ghcr.io/etnt/cryptic:latest
 
+# Create a directory for storing the Cryptic server data
+mkdir ~/.cryptic_server
+cd ~/.cryptic_server
+
 # Setup the server certificates (one-time step)
 # Creates ca.crt, ca.key, server.crt, server.key in ./priv/ssl/
 mkdir -p priv/ssl priv/ca/bootstrap
@@ -65,6 +84,7 @@ gpg --armor --export alice@cryptic.local > priv/ca/bootstrap/alice.gpg
 
 # Run the server (requires certificates in ./priv/ssl/)
 # Here we show how to expose port 9898 instead of the default (8443)
+# For debug log output, add: -e CRYPTIC_DEBUG=true
 mkdir -p logs data/ca/bootstrap
 docker run -d \
   --name cryptic-server \
@@ -84,61 +104,10 @@ docker run -d \
 # Check server logs
 docker logs -f cryptic-server
 
-# Stop the server
+# Stop the server and remove the container
 docker stop cryptic-server && docker rm cryptic-server
 ```
 
-### First Admin Bootstrap
-
-The admin bootstrap happens **before** starting the server:
-
-1. **Generate a GPG key** on your host machine (if you don't have one):
-   ```bash
-   gpg --quick-generate-key 'alice <alice@cryptic.local>' rsa4096
-   ```
-
-2. **Export the public key** to the bootstrap directory:
-   ```bash
-   gpg --armor --export alice@cryptic.local > priv/ca/bootstrap/alice.gpg
-   ```
-
-3. **Start the server** - it will read the bootstrap directory and register the admin.
-
-**Now the admin can onboard** from their client machine:
-
-```bash
-docker run -it --rm --name cryptic-client \
-  -v ~/.cryptic:/home/cryptic/.cryptic \
-  -v ~/.gnupg:/home/cryptic/.gnupg \
-  --add-host=cryptic-server:host-gateway \
-  ghcr.io/etnt/cryptic-tui:latest sh -c 'cryptic --onboard'
-```
-
-During onboarding:
-1. Use your existing GPG key (the one you just created)
-2. The fingerprint is already registered (from the bootstrap step)
-3. Request your TLS certificate
-4. Start using Cryptic!
-
-Once the first admin has a certificate, they can register other users' GPG keys
-through the admin interface, allowing those users to complete onboarding.
-
-**Note**: If you need to bootstrap multiple admin users before starting the server,
-each admin generates their GPG key and exports it:
-
-```bash
-# Each admin generates their key on their machine (no passphrase needed)
-gpg --quick-generate-key 'alice <alice@cryptic.local>' rsa4096
-gpg --quick-generate-key 'bob <bob@cryptic.local>' rsa4096
-
-# Export each public key to the bootstrap directory
-gpg --armor --export alice@cryptic.local > priv/ca/bootstrap/alice.gpg
-gpg --armor --export bob@cryptic.local > priv/ca/bootstrap/bob.gpg
-
-# Then start the server (it will read all GPG keys from priv/ca/bootstrap/)
-docker run -d --name cryptic-server ...
-```
-
 ## The Client
 
 The Cryptic TUI (Terminal User Interface) client can run in Docker to
@@ -336,8 +305,18 @@ The entrypoint script (`docker-tui-entrypoint.sh`) handles:
 
 #### Building the Image
 
+**Important**: The Dockerfile expects to be run from the **parent directory** containing both `cryptic/` and `cryptic-tui/` as subdirectories.
+
 Build the Docker image:
 ```bash
+# From the parent directory (containing both cryptic/ and cryptic-tui/)
+cd /path/to/parent-directory
+docker build -t cryptic-tui:latest -f cryptic/Dockerfile.tui .
+```
+
+Or using Docker Compose (handles build context automatically):
+```bash
+# From the cryptic directory
 docker compose build cryptic-tui
 ```
 
@@ -346,6 +325,16 @@ Build without cache (fresh build):
 docker compose build --no-cache cryptic-tui
 ```
 
+**Common Error**: If you get `COPY failed: file not found` errors, ensure you're building from the parent directory, not from within `cryptic/`:
+```bash
+# Wrong (from inside cryptic/)
+docker build -t cryptic-tui:latest -f Dockerfile.tui .  # ❌ Will fail
+
+# Correct (from parent directory)
+cd ..
+docker build -t cryptic-tui:latest -f cryptic/Dockerfile.tui .  # ✅ Works
+```
+
 #### Running the Client
 
 Run interactively (recommended):

scripts/docker-tui-entrypoint.sh

@@ -36,7 +36,7 @@ fix_permissions() {
         # Get the actual owner UID
         local owner_uid=$(stat -c %u "$dir" 2>/dev/null || stat -f %u "$dir" 2>/dev/null || echo "0")
         local cryptic_uid=$(id -u cryptic)
-        
+
         if [ "$owner_uid" != "$cryptic_uid" ]; then
             info "Fixing permissions for $dir..."
             chown -R cryptic:cryptic "$dir" 2>/dev/null || warn "Could not change ownership of $dir"
@@ -47,7 +47,7 @@ fix_permissions() {
 # Set up Erlang cookie
 setup_erlang_cookie() {
     local cookie_file="/home/cryptic/.erlang.cookie"
-    
+
     if [ -n "$ERLANG_COOKIE" ]; then
         info "Setting up Erlang cookie from environment..."
         echo -n "$ERLANG_COOKIE" > "$cookie_file"
@@ -74,14 +74,14 @@ setup_erlang_cookie() {
 # Verify certificate files exist
 check_certificates() {
     local cert_dir="/home/cryptic/.cryptic/${CRYPTIC_USERNAME}/${CRYPTIC_SERVER_HOST}_${CRYPTIC_SERVER_PORT}/certificates"
-    
+
     if [ ! -d "$cert_dir" ]; then
         warn "Certificate directory not found: $cert_dir"
         warn "You may need to run onboarding first:"
         warn "  docker compose run --rm cryptic-tui sh -c \"cryptic --onboard\""
         return 1
     fi
-    
+
     if [ ! -f "$cert_dir/${CRYPTIC_USERNAME}.crt" ] || \
        [ ! -f "$cert_dir/${CRYPTIC_USERNAME}.key" ] || \
        [ ! -f "$cert_dir/ca.crt" ]; then
@@ -93,21 +93,21 @@ check_certificates() {
         warn "Run onboarding: docker compose run --rm cryptic-tui sh -c \"cryptic --onboard\""
         return 1
     fi
-    
+
     success "Certificates found in $cert_dir"
     return 0
 }
 
 # Check GPG keyring is available (mounted from host)
 check_gpg_keyring() {
     local gpg_home="/home/cryptic/.gnupg"
-    
+
     if [ ! -d "$gpg_home" ]; then
         warn "GPG keyring not mounted: $gpg_home"
         warn "Certificate auto-renewal requires ~/.gnupg to be mounted."
         return 1
     fi
-    
+
     # Check if there are any secret keys
     if su-exec cryptic gpg --list-secret-keys 2>/dev/null | grep -q "^sec"; then
         success "GPG keyring available with secret keys"
@@ -143,39 +143,35 @@ EOF
 
 # Main execution
 main() {
-    info "Cryptic TUI Container Starting..."
-    
     # Fix permissions on mounted volumes
     fix_permissions "/home/cryptic/.cryptic"
-    
+
     # Set up Erlang cookie
     setup_erlang_cookie
-    
-    # Check certificates (warn but don't fail - user might be onboarding)
+
+    # If arguments are given, just execute the command directly as cryptic user
+    if [ $# -gt 0 ]; then
+        exec su-exec cryptic "$@"
+    fi
+
+    # Check certificates (warn but don't fail - user might need to onboard)
     check_certificates || warn "Continuing without certificates (use --onboard to set up)..."
-    
+
     # Check GPG keyring is available (warn but don't fail)
     check_gpg_keyring || warn "Continuing without GPG keyring..."
-    
+
     # Show connection info
     show_connection_info
-    
-    # If command is cryptic-tui (default), run bin/cryptic --tui
-    if [ "$1" = "cryptic-tui" ]; then
-        info "Starting Cryptic TUI via bin/cryptic --tui..."
-        
-        # Execute as cryptic user with bin/cryptic script
-        exec su-exec cryptic /opt/cryptic/bin/cryptic --tui \
-            -u "${CRYPTIC_USERNAME}" \
-            -s "${CRYPTIC_SERVER_HOST}" \
-            -p "${CRYPTIC_SERVER_PORT}" \
-            --name "${CRYPTIC_NODE_NAME}" \
-            $([ "${CRYPTIC_ENABLE_DB}" = "true" ] && echo "--enable-db")
-    else
-        # Run custom command as cryptic user
-        info "Running custom command: $@"
-        exec su-exec cryptic "$@"
-    fi
+
+    info "Starting Cryptic TUI via bin/cryptic --tui..."
+
+    # Execute as cryptic user with bin/cryptic script
+    exec su-exec cryptic /opt/cryptic/bin/cryptic --tui \
+        -u "${CRYPTIC_USERNAME}" \
+        -s "${CRYPTIC_SERVER_HOST}" \
+        -p "${CRYPTIC_SERVER_PORT}" \
+        --name "${CRYPTIC_NODE_NAME}" \
+        $([ "${CRYPTIC_ENABLE_DB}" = "true" ] && echo "--enable-db")
 }
 
 main "$@"