Sasha Client Deployment Guide

Status: Complete
Generated: 2025-08-13 12:30 UTC

This comprehensive guide covers the complete deployment process for Sasha Studio clients on the Sliplane platform, including automated deployment, SSH debugging, and documentation management.

Quick Start

Deploy a new client in 3 commands:

cd /Users/lindsaysmith/Documents/lambda1.nosync/sasha/client-management

# Create client
echo -e "MyClient AI\nMyCompany\n#FF5733" | ./manage-clients.sh create myclient

# Deploy (includes SSH setup)
./manage-clients.sh deploy myclient

# Get access info
./manage-clients.sh info myclient

System Architecture
Prerequisites
Client Management
Deployment Process
SSH Access
Volume Management
Documentation
Troubleshooting

System Architecture

Overview

Sasha Studio uses a shared Docker image architecture where all clients run the same base image (linzoid/sasha-studio:latest) with client-specific configuration via environment variables.

Key Components

Shared Docker Image: Single image for all clients
2-Volume Layout: Simplified storage (home + data)
Sliplane API: Automated deployment and management
SSH Integration: Built-in debugging access
Documentation Bundle: Pre-built guides and specialists

Directory Structure

client-management/
├── manage-clients.sh        # Main management interface
├── clients/                 # Client configurations
│   ├── template/           # Template for new clients
│   └── {client}/          # Individual client configs
├── scripts/                # Automation scripts
│   ├── deploy-with-api.sh # API deployment
│   └── check-status.sh    # Status checking
└── lib/                   # Shared libraries
    └── sliplane-api.sh   # API functions

Prerequisites

Required Setup

Sliplane Account: API credentials in .env

SLIPLANE_API_TOKEN=api_rw_xxx
SLIPLANE_ORG_ID=org_xxx
SLIPLANE_SERVER_ID=server_xxx
SLIPLANE_PROJECT_ID=project_xxx

Docker Hub Access: For image linzoid/sasha-studio

SSH Key (optional): For debugging access

# Generate if needed
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Initial Configuration

# Set up API credentials
./setup-api.sh

# Test connection
./scripts/test-api.sh

Client Management

List Clients

./manage-clients.sh list

Output shows:

Client name and ID
Deployment status
Version information
Domain URL
SSH configuration status

Create Client

# Interactive
./manage-clients.sh create myclient

# Non-interactive
CLIENT_ID="myclient"
CLIENT_NAME="MyClient AI"
COMPANY_NAME="MyCompany"
echo -e "$CLIENT_NAME\n$COMPANY_NAME\n#FF5733" | ./manage-clients.sh create $CLIENT_ID

View Client Info

./manage-clients.sh info myclient

Shows:

Configuration details
Deployment status
SSH access info
Volume configuration
History log

Delete Client

# Delete config only
./manage-clients.sh delete myclient

# Delete with volumes (ALL DATA)
./manage-clients.sh delete myclient --with-volumes

# Dry run (preview)
./manage-clients.sh delete myclient --with-volumes --dry-run

Deployment Process

Automated Deployment

The deployment script handles everything automatically:

./manage-clients.sh deploy myclient

This performs:

Service creation/update on Sliplane
Volume configuration (2-volume layout)
Environment variable setup
Docker image deployment
SSH key attachment (if available)
Configuration update with SSH info
History tracking

Manual Deployment Script

For direct control:

./scripts/deploy-with-api.sh myclient

# Dry run mode
./scripts/deploy-with-api.sh myclient --dry-run

Check Deployment Status

# Quick status
./manage-clients.sh status myclient

# Detailed API check
./scripts/check-status.sh myclient

Environment Variables

Each deployment sets:

NODE_ENV=production
COMPANY_NAME - Client company name
SESSION_SECRET - Auto-generated
JWT_SECRET - Auto-generated
DOCS_PATH=/home/nodejs/workspace/docs
HOME=/home/nodejs
Path configurations for Claude CLI

SSH Access

Automatic SSH Setup

SSH is automatically configured during deployment if ~/.ssh/id_rsa.pub exists.

Get SSH Connection

# Get connection string
./manage-clients.sh ssh myclient

# Output:
ssh -p 22222 service_xxx@server_xxx.sliplane.app

Attach SSH Key

For existing deployments without SSH:

./manage-clients.sh ssh-attach myclient

Using SSH Access

Once connected:

# Connect
ssh -p 22222 service_xxx@server_xxx.sliplane.app

# Common debugging commands
tail -f /app/logs/*.log                        # View logs
ls -la /home/nodejs/workspace/docs/            # Check documentation
ps aux | grep node                             # Check processes
env | grep -E 'DOCS|CLAUDE|HOME'              # Verify environment
sqlite3 /app/data/sasha.db ".tables"          # Database inspection

SSH Configuration Storage

SSH info is automatically stored in client config:

{
  "deployment": {
    "sliplane": {
      "ssh_enabled": true,
      "ssh_command": "ssh -p 22222 service_xxx@server.sliplane.app"
    }
  },
  "status": {
    "ssh_configured": true
  }
}

Volume Management

Simplified 2-Volume Layout

Each client has two persistent volumes:

{client}-home (5Gi)
- Mount: /home/nodejs
- Contains: All user data, Claude config, projects, workspaces
{client}-data (10Mi)
- Mount: /app/data
- Contains: SQLite database

List Volumes

# All volumes
./manage-clients.sh volumes

# Client-specific
./manage-clients.sh volumes myclient

Cleanup Orphaned Volumes

# Find orphaned volumes
./manage-clients.sh cleanup --dry-run

# Remove orphaned volumes
./manage-clients.sh cleanup

Manual Volume Management

For direct control:

./scripts/manage-volumes.sh list
./scripts/manage-volumes.sh cleanup

Documentation

Documentation Build Process

See deployed-md-files build guide

Documentation Paths

In deployed containers:

Markdown: /home/nodejs/workspace/docs/
HTML: /home/nodejs/workspace/html-static/
Guides: /home/nodejs/workspace/docs/guides/
Specialists: /home/nodejs/workspace/docs/specialists/

Verify Documentation

# Via SSH
ssh -p 22222 service_xxx@server.sliplane.app
ls -la /home/nodejs/workspace/docs/guides/
cat /home/nodejs/workspace/docs/CLAUDE.md

Troubleshooting

Common Issues

Service Not Starting

# Check deployment status
./scripts/check-status.sh myclient

# Get logs via SSH
./manage-clients.sh ssh myclient
# Then: tail -f /app/logs/*.log

Empty Documentation Directories

# Verify Docker build included docs
docker run --rm -it linzoid/sasha-studio:latest sh -c "ls -la /home/nodejs/workspace/docs/"

# Check via SSH
ssh -p 22222 service_xxx@server.sliplane.app
ls -la /home/nodejs/workspace/docs/

SSH Connection Failed

# Verify SSH key exists
ls -la ~/.ssh/id_rsa.pub

# Re-attach SSH key
./manage-clients.sh ssh-attach myclient

# Check client info
./manage-clients.sh info myclient

API Connection Issues

# Test API
./scripts/test-api.sh

# Check credentials
cat .env | grep SLIPLANE

# Re-run setup if needed
./setup-api.sh

Debug Commands

Full Diagnostic

CLIENT="myclient"

# 1. Check configuration
./manage-clients.sh info $CLIENT

# 2. Test API
./scripts/test-api.sh

# 3. Check deployment
./scripts/check-status.sh $CLIENT

# 4. Get SSH access
./manage-clients.sh ssh $CLIENT

# 5. Check history
./manage-clients.sh history $CLIENT

Container Health Check

# Via SSH
ssh -p 22222 service_xxx@server.sliplane.app

# Run checks
curl http://localhost:3005/api/health
ps aux | grep node
df -h
free -m

Best Practices

1. Always Use Dry-Run First

./scripts/deploy-with-api.sh myclient --dry-run
./manage-clients.sh delete myclient --dry-run

2. Monitor Deployment

# Deploy
./manage-clients.sh deploy myclient

# Wait and check
sleep 30
./manage-clients.sh status myclient

3. Keep Backups

Client configs are automatically backed up on deletion in:

backups/deleted_YYYYMMDD_HHMMSS/

4. Track Changes

All actions are logged in client history:

./manage-clients.sh history myclient

5. Use SSH for Debugging

Don't guess - connect and inspect:

./manage-clients.sh ssh myclient

Advanced Usage

Batch Operations

# Deploy multiple clients
for client in atom1 atom2 atom3; do
  ./manage-clients.sh deploy $client
  sleep 10
done

# Check all statuses
for client in atom1 atom2 atom3; do
  echo "=== $client ==="
  ./manage-clients.sh status $client
done

Custom Environment Variables

Edit clients/{client}/config.json:

{
  "environment": {
    "CUSTOM_VAR": "value",
    "API_KEY": "secret"
  }
}

Update Existing Deployment

# Modify config
vim clients/myclient/config.json

# Redeploy
./manage-clients.sh deploy myclient

Quick Reference

Essential Commands

# Management
./manage-clients.sh list                      # List all clients
./manage-clients.sh info CLIENT               # Show client details
./manage-clients.sh create CLIENT             # Create new client
./manage-clients.sh deploy CLIENT             # Deploy client
./manage-clients.sh status CLIENT             # Check status
./manage-clients.sh delete CLIENT             # Delete client
./manage-clients.sh ssh CLIENT                # Get SSH access
./manage-clients.sh history CLIENT            # View history

# Scripts
./scripts/test-api.sh                         # Test API connection
./scripts/deploy-with-api.sh CLIENT           # Direct deployment
./scripts/check-status.sh CLIENT              # Detailed status

URLs and Endpoints

Application: https://{client}.sliplane.app
Health Check: https://{client}.sliplane.app/api/health
Sliplane Dashboard: https://ctrl.sliplane.io

File Locations

Client Configs: clients/{client}/config.json
API Credentials: .env
Backups: backups/
Scripts: scripts/
Libraries: lib/

Support

For issues or questions:

Check this guide and troubleshooting section
Review deployed-md-files build guide
Check Sliplane API documentation
Use SSH to debug containers directly