From 0287538584c6b5c23971e9f5c4cd7704d032781a Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Mon, 3 Mar 2025 12:33:27 -0800
Subject: [PATCH] feat(docs): Update README.md and CONTRIBUTING.md

---
 CONTRIBUTING.md | 81 ++++++++++++++++++++++++++++++++++++++++---------
 README.md       | 46 +++++++++++++++++++++++-----
 2 files changed, 104 insertions(+), 23 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0fac6c5b7..1a629aaa3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -127,33 +127,84 @@ Using clear and consistent commit messages makes it easier for everyone to under
 
 To set up your local development environment:
 
+### Option 1: Using Docker (Recommended)
+
+Docker provides a consistent development environment with all dependencies pre-configured.
+
+1. **Clone the Repository:**
+
+   ```bash
+   git clone https://github.com/<your-username>/sim.git
+   cd sim
+   ```
+
+2. **Start the Docker Environment:**
+
+   ```bash
+   docker compose up -d
+   ```
+
+   Or use the convenience script which handles environment setup and migrations:
+
+   ```bash
+   chmod +x start_simstudio_docker.sh
+   ./start_simstudio_docker.sh
+   ```
+
+   This will:
+
+   - Start a PostgreSQL database container
+   - Build and run the Next.js application with hot-reloading
+   - Set up all necessary environment variables
+   - Apply database migrations automatically
+
+3. **View Logs:**
+
+   ```bash
+   docker compose logs -f simstudio
+   ```
+
+4. **Make Your Changes:**
+   - Edit files in your local directory
+   - Changes will be automatically reflected thanks to hot-reloading
+
+### Option 2: Manual Setup
+
+If you prefer not to use Docker:
+
 1. **Clone the Repository:**
    ```bash
-   git clone https://github.com/<your-username>/sim-studio.git
+   git clone https://github.com/<your-username>/sim.git
+   cd sim
    ```
-2. **Navigate to the Project Directory:**
-   ```bash
-   cd sim-studio
-   ```
-3. **Install Dependencies:**
-   - Using Yarn:
-     ```bash
-     yarn install
-     ```
-   - Or using NPM:
+2. **Install Dependencies:**
+
+   - Using NPM:
      ```bash
      npm install
      ```
-4. **Run the Development Server:**
-   - With Yarn:
+
+3. **Set Up Environment:**
+
+   - Copy `.env.example` to `.env`
+   - Configure database connection and other required variables
+
+4. **Set Up Database:**
+
+   - You need a PostgreSQL instance running
+   - Run migrations:
      ```bash
-     yarn dev
+     npm run db:push
      ```
+
+5. **Run the Development Server:**
+
    - With NPM:
      ```bash
      npm run dev
      ```
-5. **Make Your Changes and Test Locally.**
+
+6. **Make Your Changes and Test Locally.**
 
 ---
 
diff --git a/README.md b/README.md
index b0e99f616..76f0467a3 100644
--- a/README.md
+++ b/README.md
@@ -9,22 +9,52 @@
 1. Self-host
 2. [Join the Waitlist](https://simstudio.ai) for the cloud-hosted beta
 
-## Getting Started
+## Quick Start
 
-1. Clone the repository
+The quickest way to get Sim Studio running locally:
+
+1. **Clone the repository**
 
 ```bash
 git clone https://github.com/simstudioai/sim.git
-cd sim-studio
+cd sim
 ```
 
-2. Install dependencies
+2. **Start with Docker**
+
+```bash
+docker compose up -d
+```
+
+Or use the convenience script for automatic setup:
+
+```bash
+chmod +x start_simstudio_docker.sh
+./start_simstudio_docker.sh
+```
+
+This will start Sim Studio at http://localhost:3000 with a local PostgreSQL database.
+
+3. **[Optional] Configure Your Environment**
+
+Copy `.env.example` to `.env` and configure:
+
+- Authentication secrets (required for login functionality)
+- API keys:
+  - **Essential**: Resend API key (for authentication emails)
+  - **Optional**: OpenAI, Anthropic, etc. (for specific block functionality)
+
+## Manual Setup
+
+If you prefer not to use Docker:
+
+1. **Install dependencies**
 
 ```bash
 npm install
 ```
 
-3. Set up your environment variables
+2. **Set up environment variables**
 
 Copy `.env.example` to `.env` and configure:
 
@@ -32,20 +62,20 @@ Copy `.env.example` to `.env` and configure:
 - Authentication secret
 - Email provider (Resend)
 
-4. Set up the database
+3. **Set up the database**
 
 ```bash
 # Push the database schema
 npx drizzle-kit push
 ```
 
-5. Start the development server
+4. **Start the development server**
 
 ```bash
 npm run dev
 ```
 
-6. Open [http://localhost:3000](http://localhost:3000)
+5. **Open [http://localhost:3000](http://localhost:3000)**
 
 ## Tech Stack