From 1fdc40eaef9d403b64dbfd8e3fbe12761c965fce Mon Sep 17 00:00:00 2001
From: Cristian Branet <gbranet@dvloper.io>
Date: Tue, 27 May 2025 02:18:23 +0300
Subject: [PATCH] doc update - Clarified startup options for local development
 - `skyvern run server` vs Docker Compose  (#2442)

---
 README.md                   | 46 +++++++++++++++++++++++++++++++++++++
 skyvern/cli/init_command.py |  6 ++++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3e34eefd..da94cc86 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,52 @@ This quickstart guide will walk you through getting Skyvern up and running on yo
    ```
 3. Navigate to `http://localhost:8080` in your browser to start using the UI
 
+## Local vs. Docker
+
+Skyvern supports two startup options for local development:
+
+**Before Option 1**
+* If using Option 1, working in a virtual environment may improve the overall experience. Here's how to activate it:
+
+  ```bash
+  python3 -m venv skyvern-env/
+  cd skyvern
+  source ../skyvern-env/bin/activate
+  pip install skyvern (Only if not already installed)
+  pip install -e .
+  ``` 
+
+  Deactivation:
+  ```bash
+  deactivate
+  ```
+
+**Option 1: Native (Postgres created by the CLI wizard)**
+
+* Use the CLI wizard to spin up a disposable Postgres container, then run the backend natively.
+* **Start with:**
+  ```bash
+  skyvern init
+  skyvern run server
+  ```
+* This reuses the Postgres container created by the wizard.
+
+**Option 2: Docker Compose (Postgres created with Compose)**
+
+* Use Docker Compose to start all services, including a new Postgres container.
+* **Start with:**
+  ```bash
+  docker compose up -d
+  ```
+* This launches a new Postgres instance inside Compose.
+
+> **Important:** Only one Postgres container can run on port 5432 at a time. If you switch from the CLI-managed Postgres to Docker Compose, you must first remove the original container:
+> ```bash
+> docker rm -f postgresql-container
+> ```
+
+If you encounter any database related errors while using Docker to run Skyvern, check which Postgres container is running with `docker ps`.
+
 ## Model Context Protocol (MCP)
 See the MCP documentation [here](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)
 
diff --git a/skyvern/cli/init_command.py b/skyvern/cli/init_command.py
index cc0a9106..2d96089b 100644
--- a/skyvern/cli/init_command.py
+++ b/skyvern/cli/init_command.py
@@ -76,7 +76,11 @@ def init(
 
         console.print("🌐 [bold blue]Setting Skyvern Base URL to: http://localhost:8000[/bold blue]")
         update_or_add_env_var("SKYVERN_BASE_URL", "http://localhost:8000")
-
+        
+        console.print("\n[bold yellow]To run Skyvern you can either:[/bold yellow]")
+        console.print("• [green]skyvern run server[/green]  (reuses the DB we just created)")
+        console.print("• [cyan]docker compose up -d[/cyan]  (starts a new Postgres inside Compose; you may stop the first container with: [magenta]docker rm -f postgresql-container[/magenta])")
+        console.print("\n[italic]Only one Postgres container can run on the host's port 5432 at a time. If you switch to Docker Compose, remove the original with:[/italic] [magenta]docker rm -f postgresql-container[/magenta]")
     else:
         console.print(Panel("[bold purple]Cloud Deployment Setup[/bold purple]", border_style="purple"))
         base_url = Prompt.ask("Enter Skyvern base URL", default="https://api.skyvern.com", show_default=True)