Enhance Docker Compose setup and documentation

README.md

@@ -94,11 +94,32 @@ This allows developers to deploy production agents that can scale beautifully to
   }
   ```
 
+## Quick Start with Docker Compose
+
+Get Exosphere running locally in under 2 minutes:
+
+```bash
+# Option 1: With cloud MongoDB (recommended)
+echo "MONGO_URI=your-mongodb-connection-string" > .env
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
+docker compose up -d
+
+# Option 2: With local MongoDB (development)
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
+docker compose -f docker-compose-with-mongodb.yml up -d
+```
+
+Access your services:
+- **Dashboard**: http://localhost:3000
+- **API**: http://localhost:8000
+
+> **📝 Note**: This configuration is for **development and testing only**. For production deployments, environment variable customization, and advanced configuration options, please read the complete **[Docker Compose Setup Guide](https://docs.exosphere.host/docker-compose-setup)**.
+
 ## Documentation
 
 For comprehensive documentation and guides, check out:
 
-
+- **[Docker Compose Setup](https://docs.exosphere.host/docker-compose-setup)**: Complete guide for running Exosphere locally with Docker Compose.
 - **[Getting Started Guide](https://docs.exosphere.host/getting-started)**
 - **[State Manager Setup Guide](https://docs.exosphere.host/exosphere/state-manager-setup)**: Step-by-step instructions for running the Exosphere backend locally or in production.
 - **[Dashboard Guide](https://docs.exosphere.host/exosphere/dashboard)**: Learn how to set up and use the Exosphere web dashboard.

docker-compose/README.md

@@ -0,0 +1,266 @@
+# Exosphere Docker Compose Quick Start
+
+This guide helps you quickly start the Exosphere project locally using Docker Compose with a single command.
+
+## 📥 Download Docker Compose Files
+
+First, download the Docker Compose files from the GitHub repository:
+
+### Option 1: Download Both Files
+
+```bash
+# Download docker-compose file for cloud MongoDB (recommended)
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
+
+# Download docker-compose file with local MongoDB included
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
+```
+
+### Option 2: Using wget
+
+```bash
+# Download docker-compose file for cloud MongoDB (recommended)
+wget https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
+
+# Download docker-compose file with local MongoDB included
+wget https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
+```
+
+
+## 🚀 Quick Start
+
+We **recommend using a cloud MongoDB managed service** (MongoDB Atlas, AWS DocumentDB, etc.) for better performance, reliability, and security.
+
+### Option 1: With Cloud MongoDB (Recommended)
+
+1. Set up a cloud MongoDB instance (MongoDB Atlas, AWS DocumentDB, etc.)
+
+2. Create a `.env` file with your MongoDB connection:
+   ```bash
+   MONGO_URI=mongodb+srv://username:password@your-cluster.mongodb.net/
+   ```
+
+3. Download and start the services:
+   ```bash
+   curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml && docker compose -f docker-compose.yml up -d
+   ```
+
+This will start:
+- Exosphere State Manager (port 8000)  
+- Exosphere Dashboard (port 3000)
+
+### Option 2: With Local MongoDB (Development Only)
+
+For quick local testing only:
+
+```bash
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml && docker compose -f docker-compose-with-mongodb.yml up -d
+```
+
+This will start:
+- MongoDB database (port 27017)
+- Exosphere State Manager (port 8000)  
+- Exosphere Dashboard (port 3000)
+
+## 🧪 Beta Version
+
+To run the latest beta version of Exosphere with the newest features, replace container tags with `beta-latest`:
+
+### Quick Beta Setup with Cloud MongoDB
+```bash
+# Download and modify for beta with cloud MongoDB
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
+sed -i 's/:latest/:beta-latest/g' docker-compose.yml
+# Set your MONGO_URI in .env file, then:
+docker compose -f docker-compose.yml up -d
+```
+
+### Quick Beta Setup with Local MongoDB
+```bash
+# Download and modify for beta with local MongoDB
+curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
+sed -i 's/:latest/:beta-latest/g' docker-compose-with-mongodb.yml
+docker compose -f docker-compose-with-mongodb.yml up -d
+```
+
+### Manual Beta Setup (Alternative)
+
+1. Download the docker-compose file
+2. Edit the file and change:
+   ```yaml
+   # Change from:
+   image: ghcr.io/exospherehost/exosphere-state-manager:latest
+   image: ghcr.io/exospherehost/exosphere-dashboard:latest
+
+   # To:
+   image: ghcr.io/exospherehost/exosphere-state-manager:beta-latest
+   image: ghcr.io/exospherehost/exosphere-dashboard:beta-latest
+   ```
+3. Start the services with `docker compose up -d`
+
+## 📋 Environment Variables
+
+### Environment Variables for State Manager
+
+| Variable | Description | Default Value | Required |
+|----------|-------------|---------------|----------|
+| `MONGO_URI` | MongoDB connection string | - | ✅ (for docker-compose.yml) |
+| `STATE_MANAGER_SECRET` | API key for state manager authentication | `exosphere@123` | ⚙️ (has default) |
+| `MONGO_DATABASE_NAME` | MongoDB database name | `exosphere` | ⚙️ (has default) |
+| `SECRETS_ENCRYPTION_KEY` | Base64-encoded encryption key for secrets | `YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=` | ⚙️ (has default) |
+
+> **⚠️ Important**: The `SECRETS_ENCRYPTION_KEY` is used to encrypt secrets in the database. Changing this value will make existing encrypted secrets unreadable. Only change this key when setting up a new instance or if you're okay with losing access to existing encrypted data.
+
+### Dashboard Environment Variables (All Optional)
+
+| Variable | Description | Default Value |
+|----------|-------------|---------------|
+| `NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL` | State manager API URL | `http://exosphere-state-manager:8000` |
+| `NEXT_PUBLIC_DEFAULT_NAMESPACE` | Default namespace for workflows | `WhatPeopleWant` |
+| `NEXT_PUBLIC_DEFAULT_API_KEY` | Default API key for dashboard | `exosphere@123` |
+
+### MongoDB Local Setup Variables (for docker-compose-with-mongodb.yml only)
+
+| Variable | Description | Default Value |
+|----------|-------------|---------------|
+| `MONGO_INITDB_ROOT_USERNAME` | MongoDB root username | `admin` |
+| `MONGO_INITDB_ROOT_PASSWORD` | MongoDB root password | `password` |
+| `MONGO_INITDB_DATABASE` | Initial MongoDB database | `exosphere` |
+
+### SDK Environment Variables
+
+To use the Exosphere Python SDK with your running instance, set these environment variables in your development environment:
+
+| Variable | Description | Example Value |
+|----------|-------------|---------------|
+| `EXOSPHERE_STATE_MANAGER_URI` | URL where the state manager is running | `http://localhost:8000` |
+| `EXOSPHERE_API_KEY` | API key for authentication (same as STATE_MANAGER_SECRET) | `exosphere@123` |
+
+**Example SDK setup**:
+```bash
+# Set environment variables for SDK
+export EXOSPHERE_STATE_MANAGER_URI=http://localhost:8000
+export EXOSPHERE_API_KEY=exosphere@123
+
+# Or add to your .env file for your Python project
+echo "EXOSPHERE_STATE_MANAGER_URI=http://localhost:8000" >> .env
+echo "EXOSPHERE_API_KEY=exosphere@123" >> .env
+```
+
+## 🔧 Custom Configuration
+
+### Using Your Own Environment Variables
+
+Create a `.env` file in the same directory as your docker-compose file:
+
+```bash
+# MongoDB Configuration (REQUIRED for docker-compose.yml)
+MONGO_URI=mongodb+srv://username:password@your-cluster.mongodb.net/
+
+# Optional Configuration (has defaults)
+MONGO_DATABASE_NAME=exosphere
+STATE_MANAGER_SECRET=your-custom-secret-key
+SECRETS_ENCRYPTION_KEY=your-base64-encoded-encryption-key
+
+# Dashboard Configuration (Optional)
+NEXT_PUBLIC_DEFAULT_NAMESPACE=YourNamespace
+NEXT_PUBLIC_DEFAULT_API_KEY=your-custom-secret-key
+
+# For local MongoDB setup only (docker-compose-with-mongodb.yml)
+MONGO_INITDB_ROOT_USERNAME=admin
+MONGO_INITDB_ROOT_PASSWORD=password
+MONGO_INITDB_DATABASE=exosphere
+```
+
+Then run with your custom configuration:
+```bash
+# For cloud MongoDB (recommended)
+docker compose -f docker-compose.yml up -d
+
+# For local MongoDB
+docker compose -f docker-compose-with-mongodb.yml up -d
+```
+
+**Note**: The docker-compose files now automatically use `.env` files in the same directory and provide sensible defaults for all optional variables.
+
+### Generating a New Encryption Key
+
+To generate a secure encryption key for `SECRETS_ENCRYPTION_KEY`:
+
+```bash
+# Using Python
+python -c "import base64; import os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"
+
+# Using OpenSSL
+openssl rand -base64 32
+```
+
+## 🌐 Access Your Services
+
+After running the Docker Compose command:
+
+- **Exosphere Dashboard**: http://localhost:3000
+- **State Manager API**: http://localhost:8000
+- **MongoDB** (if using with-mongodb): http://localhost:27017
+- **API Documentation**: http://localhost:8000/docs
+
+## 🛠️ Development Commands
+
+```bash
+# Start services in background
+docker compose -f docker-compose-with-mongodb.yml up -d
+
+# View logs
+docker compose -f docker-compose-with-mongodb.yml logs -f
+
+# Stop services
+docker compose -f docker-compose-with-mongodb.yml down
+
+# Stop services and remove volumes (⚠️ This will delete your data)
+docker compose -f docker-compose-with-mongodb.yml down -v
+
+# Pull latest images
+docker compose -f docker-compose-with-mongodb.yml pull
+
+# Restart a specific service
+docker compose -f docker-compose-with-mongodb.yml restart exosphere-state-manager
+```
+
+## 🔍 Troubleshooting
+
+### Check Service Health
+
+```bash
+# Check if all containers are running
+docker compose -f docker-compose-with-mongodb.yml ps
+
+# Check state manager health
+curl http://localhost:8000/health
+
+# View container logs
+docker compose -f docker-compose-with-mongodb.yml logs exosphere-state-manager
+```
+
+### Common Issues
+
+1. **Port already in use**: Change the port mappings in the docker-compose file if ports 3000, 8000, or 27017 are already in use.
+
+2. **MongoDB connection issues**: Ensure MongoDB is fully started before the state manager. The `depends_on` configuration handles this automatically.
+
+3. **Authentication errors**: Verify your `STATE_MANAGER_SECRET` matches between the state manager and dashboard configuration.
+
+
+## 📖 Next Steps
+
+Once your Exosphere instance is running:
+
+1. Visit the dashboard at http://localhost:3000
+2. Check out the [official documentation](https://docs.exosphere.host) 
+3. Follow the [Getting Started Guide](https://docs.exosphere.host/getting-started) to create your first workflow
+4. Explore the [State Manager API](http://localhost:8000/docs) for advanced usage
+
+## 🤝 Support
+
+- [Documentation](https://docs.exosphere.host)
+- [Discord Community](https://discord.com/invite/zT92CAgvkj)
+- [GitHub Issues](https://github.com/exospherehost/exospherehost/issues)

docker-compose/docker-compose-with-mongodb.yml

@@ -0,0 +1,56 @@
+services:
+  mongodb:
+    image: mongo:7.0
+    container_name: mongodb
+    restart: unless-stopped
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MONGO_INITDB_ROOT_USERNAME:-admin}
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD:-password}
+      MONGO_INITDB_DATABASE: ${MONGO_INITDB_DATABASE:-exosphere}
+    volumes:
+      - mongodb_data:/data/db
+    ports:
+      - "27017:27017"
+    networks:
+      - exosphere-network
+
+  exosphere-state-manager:
+    image: ghcr.io/exospherehost/exosphere-state-manager:latest
+    container_name: whatpeoplewant-state-manager
+    restart: unless-stopped
+    environment:
+      - MONGO_URI=${MONGO_URI:-mongodb://admin:password@mongodb:27017/exosphere?authSource=admin}
+      - STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET:-exosphere@123}
+      - MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME:-exosphere}
+      - SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY:-YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=}
+    depends_on:
+      - mongodb
+    ports:
+      - "8000:8000"
+    networks:
+      - exosphere-network
+
+  exosphere-dashboard:
+    image: ghcr.io/exospherehost/exosphere-dashboard:latest
+    container_name: whatpeoplewant-dashboard
+    restart: unless-stopped
+    environment:
+      - NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL=${NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL:-http://exosphere-state-manager:8000}
+      - NEXT_PUBLIC_DEFAULT_NAMESPACE=${NEXT_PUBLIC_DEFAULT_NAMESPACE:-WhatPeopleWant}
+      - NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY:-exosphere@123}
+    depends_on:
+      - mongodb
+      - exosphere-state-manager
+    ports:
+      - "3000:3000"
+    networks:
+      - exosphere-network
+
+volumes:
+  mongodb_data:
+    driver: local
+
+networks:
+  exosphere-network:
+    driver: bridge
+    attachable: true

docker-compose/docker-compose.yml

@@ -0,0 +1,34 @@
+services:
+  exosphere-state-manager:
+    image: ghcr.io/exospherehost/exosphere-state-manager:latest
+    container_name: whatpeoplewant-state-manager
+    restart: unless-stopped
+    environment:
+      - MONGO_URI=${MONGO_URI}
+      - STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET:-exosphere@123}
+      - MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME:-exosphere}
+      - SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY:-YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=}
+    ports:
+      - "8000:8000"
+    networks:
+      - exosphere-network
+
+  exosphere-dashboard:
+    image: ghcr.io/exospherehost/exosphere-dashboard:latest
+    container_name: whatpeoplewant-dashboard
+    restart: unless-stopped
+    environment:
+      - NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL=${NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL:-http://exosphere-state-manager:8000}
+      - NEXT_PUBLIC_DEFAULT_NAMESPACE=${NEXT_PUBLIC_DEFAULT_NAMESPACE:-WhatPeopleWant}
+      - NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY:-exosphere@123}
+    depends_on:
+      - exosphere-state-manager
+    ports:
+      - "3000:3000"
+    networks:
+      - exosphere-network
+
+networks:
+  exosphere-network:
+    driver: bridge
+    attachable: true