Skip to content

docs: improve local development setup documentation #2783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shige wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: improve local development setup documentation #2783

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1279858
docs: improve local development setup documentation
shige Mar 3, 2026
18a92cb
docs: update PostgreSQL version requirement to 16+
shige Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions .continuity/20260303-120000-main.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Continuity ledger (per-branch)

## Human intent (must not be overwritten)

- Discussion #2781: new contributor hit `POSTGRES_URL environment variable is required` immediately after following Quick Start
- Quick Start claims "under 2 minutes" but omits critical prerequisites (PostgreSQL, GitHub App, etc.)
- Improve documentation so contributors understand what's needed before they begin

## Goal (incl. success criteria)

- README Quick Start lists real prerequisites and correct commands
- CONTRIBUTING.md has step-by-step local development setup
- .env.example clearly marks required vs optional variables
- A new contributor reading these docs can set up the project without surprise errors

## Constraints/Assumptions

- Documentation-only changes (no code changes)
- Node.js 24+ per package.json engines field
- GitHub App credentials validated at boot in `apps/studio.giselles.ai/app/giselle.ts`
- POSTGRES_URL validated lazily but needed for vector store operations

## Key decisions

- Replaced "under 2 minutes" Quick Start with honest prerequisites + setup steps
- Added full development setup guide to CONTRIBUTING.md with numbered steps
- Reorganized .env.example with `# Required` / `# Optional` section headers
- Moved GitHub App variables from commented-out "for development only" section to required section

## State

- All three files updated
- `pnpm format` passes
- `pnpm tidy` passes

## Done

- Updated README.md Quick Start section
- Updated CONTRIBUTING.md with development environment setup guide
- Updated .env.example with required/optional markers and uncommented GitHub App vars

## Now

- N/A (complete)

## Next

- N/A (complete)

## Open questions (UNCONFIRMED if needed)

- None

## Working set (files/ids/commands)

- `README.md` (modified)
- `CONTRIBUTING.md` (modified)
- `apps/studio.giselles.ai/.env.example` (modified)
71 changes: 71 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,77 @@ Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in

## Development environment setup

### Prerequisites

| Requirement | Version | Check |
|-------------|---------|-------|
| Node.js | 24+ | `node -v` |
| pnpm | 10+ | `pnpm -v` |
| PostgreSQL | 16+ | `psql --version` |

### 1. Clone and install

```bash
git clone https://github.com/giselles-ai/giselle.git
cd giselle
pnpm install
```

### 2. Configure environment variables

```bash
cp apps/studio.giselles.ai/.env.example apps/studio.giselles.ai/.env.local
```

Open `.env.local` and fill in the **required** variables (marked in the file):

| Variable | Description |
|----------|-------------|
| `POSTGRES_URL` | PostgreSQL connection string (e.g. `postgres://user:pass@localhost:5432/giselle`) |
| `GITHUB_APP_ID` | Your GitHub App's ID |
| `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) |
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GITHUB_APP_PRIVATE_KEY is described as “PEM format”, but .env.local typically can’t safely store a raw multi-line PEM without converting newlines (e.g., replacing line breaks with \n). Consider adding a short note about the expected formatting so new contributors don’t paste a multi-line key that dotenv parses incorrectly.

Suggested change
| `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) |
| `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key in PEM format, with line breaks replaced by `\n` so it fits on a single line in `.env.local` |

Copilot uses AI. Check for mistakes.
| `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID |
| `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret |
| `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret |

Comment on lines +36 to +41
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This “required variables” list is missing COOKIE_SECRET, which is required for signed session cookies (signed-cookie hard-throws when it’s unset). Please include it in the required variables table so local setup doesn’t fail at runtime.

Suggested change
| `GITHUB_APP_ID` | Your GitHub App's ID |
| `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) |
| `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID |
| `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret |
| `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret |
| `COOKIE_SECRET` | Secret used to sign session cookies (required for signed-cookie) |
| `GITHUB_APP_ID` | Your GitHub App's ID |
| `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) |
| `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID |
| `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret |
| `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret |

Copilot uses AI. Check for mistakes.
You also need at least one AI provider API key:

| Variable | Provider |
|----------|----------|
| `OPENAI_API_KEY` | OpenAI |
| `ANTHROPIC_API_KEY` | Anthropic |
| `GOOGLE_AI_API_KEY` | Google AI |
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Google provider env var name here (GOOGLE_AI_API_KEY) doesn’t match what the codebase expects for Gemini embeddings (GOOGLE_GENERATIVE_AI_API_KEY). Please update the variable name (and consider mentioning COHERE_API_KEY if Cohere embedding profiles are used locally).

Suggested change
| `GOOGLE_AI_API_KEY` | Google AI |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google AI (Gemini) |
| `COHERE_API_KEY` | Cohere |

Copilot uses AI. Check for mistakes.

All other variables in `.env.example` are optional for local development.

> **Tip:** To create a GitHub App for development, see [GitHub's documentation](https://docs.github.com/en/apps/creating-github-apps). Set the homepage URL to `http://localhost:3000` and the callback URL to `http://localhost:3000/api/auth/callback/github-app`.

### 3. Set up the database

Create a PostgreSQL database and make sure `POSTGRES_URL` in `.env.local` points to it:

```bash
createdb giselle
```

Run migrations to set up the schema:

```bash
cd apps/studio.giselles.ai
npx drizzle-kit push
cd ../..
Comment on lines +64 to +67
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# 1. Check package.json for drizzle scripts and dependencies
echo "=== Checking package.json for drizzle-related scripts ==="
rg -n 'drizzle|scripts' package.json -A 5 -B 5 | head -100

# 2. Verify drizzle-kit is in pnpm-lock.yaml
echo -e "\n=== Checking pnpm-lock.yaml for drizzle-kit ==="
rg -n 'drizzle-kit' pnpm-lock.yaml | head -10

# 3. View exact content of CONTRIBUTING.md around lines 64-67
echo -e "\n=== CONTRIBUTING.md lines 60-70 ==="
sed -n '60,70p' CONTRIBUTING.md

Repository: giselles-ai/giselle

Length of output: 2042

🏁 Script executed:

#!/bin/bash
# 4. Search for other drizzle-kit usage in the codebase
echo "=== Searching for drizzle-kit usage patterns ==="
rg -n 'drizzle-kit' --type md --type ts --type tsx --type js --type json -C 2

# 5. Check if there's a workspace or app-specific package.json
echo -e "\n=== Checking apps/studio.giselles.ai/package.json ==="
if [ -f apps/studio.giselles.ai/package.json ]; then
  rg -n '"scripts"|drizzle' apps/studio.giselles.ai/package.json -A 3 -B 3
fi

Repository: giselles-ai/giselle

Length of output: 849

🏁 Script executed:

#!/bin/bash
# Check for other npx usages in CONTRIBUTING.md to see if pattern is consistent
echo "=== Searching for 'npx' in CONTRIBUTING.md ==="
rg -n 'npx' CONTRIBUTING.md

# Check full scripts section in apps/studio.giselles.ai/package.json
echo -e "\n=== Full scripts section in apps/studio.giselles.ai/package.json ==="
sed -n '9,30p' apps/studio.giselles.ai/package.json

Repository: giselles-ai/giselle

Length of output: 955

Use pnpm exec for database migrations in setup docs.

The documentation at line 66 uses npx drizzle-kit push, which is inconsistent with the project's pnpm-exclusive toolchain (as specified in packageManager: "pnpm@10.16.0"). Update to pnpm exec drizzle-kit push to align with project standards and all other setup commands.

Suggested docs change 
 cd apps/studio.giselles.ai
-npx drizzle-kit push
+pnpm exec drizzle-kit push
 cd ../..
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CONTRIBUTING.md` around lines 64 - 67, Replace the inconsistent npx command
in the CONTRIBUTING.md snippet: find the exact text "npx drizzle-kit push" and
change it to "pnpm exec drizzle-kit push" so the migration step uses the
project's pnpm toolchain and matches other setup commands; ensure spacing and
surrounding lines (the cd commands) remain unchanged.

```

### 4. Start the development server

```bash
pnpm dev:studio.giselles.ai
```

Open [http://localhost:3000](http://localhost:3000) — you should see the Giselle studio.

### Project structure

Giselle has both a Cloud version and a Self-hosting version, which can be found in the following directories:

- Cloud: [apps/studio.giselles.ai/](apps/studio.giselles.ai/)
Expand Down
20 changes: 3 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,29 +37,15 @@ Giselle is an open source AI for agentic workflows, enabling seamless human-AI c

## ⚡ Quick Start

Get Giselle running locally in under 2 minutes:

```bash
# Clone the repository
git clone https://github.com/giselles-ai/giselle.git
cd giselle

# Install dependencies
pnpm install

# Create environment file
touch .env.local

# Add your API key (at least one required)
echo 'OPENAI_API_KEY="your_openai_api_key_here"' >> .env.local

# Start development server
pnpm turbo dev
cp apps/studio.giselles.ai/.env.example apps/studio.giselles.ai/.env.local
pnpm dev:studio.giselles.ai
```

Open [http://localhost:3000](http://localhost:3000) and start building your AI agents!

> **Note**: You need at least one AI provider API key. Supported providers: OpenAI, Anthropic, Google AI.
> **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions.
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note says to edit .env.local, but the Quick Start creates apps/studio.giselles.ai/.env.local. Please point to the full path to avoid contributors editing/creating a root-level .env.local by mistake.

Suggested change
> **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions.
> **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `apps/studio.giselles.ai/.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions.

Copilot uses AI. Check for mistakes.

## ✨ Features

Expand Down
61 changes: 39 additions & 22 deletions apps/studio.giselles.ai/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,42 @@
# ==============================================================================
# Required — the app will not start without these
# ==============================================================================
Comment on lines +1 to +3
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file declares “Required — the app will not start without these”, but COOKIE_SECRET is not included in the required section even though core request paths call signed-cookie (which hard-throws if COOKIE_SECRET is unset). Please move COOKIE_SECRET into the Required section (and keep the later entry consistent) so new contributors don’t miss it.

Copilot uses AI. Check for mistakes.

# PostgreSQL connection string
# For local development: postgres://user:password@localhost:5432/giselle
# @see https://vercel.com/docs/storage/vercel-postgres#getting-started
POSTGRES_URL=

# GitHub App credentials (all five are validated at boot)
# @see https://docs.github.com/en/apps/creating-github-apps
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_WEBHOOK_SECRET=
Comment on lines +12 to +16
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix dotenv key ordering to satisfy current linter rule.

dotenv-linter flagged the GitHub App key order. If lint is CI-gated, this can fail checks; reorder keys per rule.

🧰 Tools
🪛 dotenv-linter (4.0.0)

[warning] 14-14: [UnorderedKey] The GITHUB_APP_CLIENT_ID key should go before the GITHUB_APP_ID key

(UnorderedKey)

[warning] 15-15: [UnorderedKey] The GITHUB_APP_CLIENT_SECRET key should go before the GITHUB_APP_ID key

(UnorderedKey)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@apps/studio.giselles.ai/.env.example` around lines 12 - 16, Reorder the
dotenv keys to satisfy dotenv-linter by arranging the GITHUB_APP_* entries
alphabetically; replace the current block (GITHUB_APP_ID,
GITHUB_APP_PRIVATE_KEY, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET,
GITHUB_APP_WEBHOOK_SECRET) with the alphabetized sequence: GITHUB_APP_CLIENT_ID,
GITHUB_APP_CLIENT_SECRET, GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY,
GITHUB_APP_WEBHOOK_SECRET so the linter passes.


# At least one AI provider API key is needed to use text generation
# OpenAI API https://openai.com/index/openai-api/
# @see https://platform.openai.com/docs/quickstart
OPENAI_API_KEY=

# ==============================================================================
# Optional — features will degrade gracefully without these
# ==============================================================================
Comment on lines +24 to +25
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Move COOKIE_SECRET out of optional env section

Labeling the rest of this file as optional is misleading for COOKIE_SECRET: if a developer follows this guidance and leaves it empty, authenticated pages will crash because getGiselleSession() calls getCookie(), and lib/signed-cookie.ts hard-fails with invariant(SECRET, "COOKIE_SECRET is not set"). This is not graceful degradation; it blocks normal logged-in flows (for example, paths that call fetchCurrentTeam() in the main app UI), so COOKIE_SECRET should be documented as required alongside the other boot-time essentials.

Useful? React with 👍 / 👎.


# Additional AI providers
# ANTHROPIC_API_KEY=
# GOOGLE_AI_API_KEY=
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The suggested Google/other provider env var names don’t match what the code reads. For embeddings, the code checks GOOGLE_GENERATIVE_AI_API_KEY (not GOOGLE_AI_API_KEY) and also uses COHERE_API_KEY for Cohere profiles. Please update these names in .env.example (and consider adding AI_GATEWAY_API_KEY as an optional entry since it’s referenced as well).

Suggested change
# GOOGLE_AI_API_KEY=
# GOOGLE_GENERATIVE_AI_API_KEY=
# COHERE_API_KEY=
# AI_GATEWAY_API_KEY=

Copilot uses AI. Check for mistakes.

Comment on lines +18 to +30
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

OPENAI_API_KEY placement conflicts with “at least one provider” requirement.

This currently reads as “OpenAI is required,” while the comment says any single provider key is enough. Move OPENAI_API_KEY to the optional provider block (or explicitly document OpenAI-only requirement).

Suggested `.env.example` adjustment 
-# At least one AI provider API key is needed to use text generation
-# OpenAI API https://openai.com/index/openai-api/
-# `@see` https://platform.openai.com/docs/quickstart
-OPENAI_API_KEY=
+# At least one AI provider API key is needed to use text generation

 # ==============================================================================
 # Optional — features will degrade gracefully without these
 # ==============================================================================

 # Additional AI providers
-# ANTHROPIC_API_KEY=
-# GOOGLE_AI_API_KEY=
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GOOGLE_AI_API_KEY=
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# At least one AI provider API key is needed to use text generation
# OpenAI API https://openai.com/index/openai-api/
# @see https://platform.openai.com/docs/quickstart
OPENAI_API_KEY=
# ==============================================================================
# Optional — features will degrade gracefully without these
# ==============================================================================
# Additional AI providers
# ANTHROPIC_API_KEY=
# GOOGLE_AI_API_KEY=
# At least one AI provider API key is needed to use text generation
# ==============================================================================
# Optional — features will degrade gracefully without these
# ==============================================================================
# Additional AI providers
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# GOOGLE_AI_API_KEY=
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@apps/studio.giselles.ai/.env.example` around lines 18 - 30, The
OPENAI_API_KEY declaration currently sits above the "Optional" block and
contradicts the comment that "At least one AI provider API key is needed";
either move the OPENAI_API_KEY line into the optional providers section
alongside ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY or update the header comment
to explicitly state OpenAI is required; update the surrounding comments so they
consistently reflect the chosen behavior and ensure OPENAI_API_KEY,
ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY are grouped with matching explanatory
text.

# Additional Postgres connection variants (Vercel Postgres)
POSTGRES_DATABASE=
POSTGRES_HOST=
POSTGRES_PASSWORD=
POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=
POSTGRES_URL_NO_SSL=
POSTGRES_USER=

# for signed cookie
COOKIE_SECRET=

Expand Down Expand Up @@ -25,21 +64,6 @@ LANGFUSE_BASEURL=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

# OpenAI API https://openai.com/index/openai-api/
# @see https://platform.openai.com/docs/quickstart
OPENAI_API_KEY=

# Vercel Postgres https://vercel.com/docs/storage/vercel-postgres
# @see https://vercel.com/docs/storage/vercel-postgres#getting-started
POSTGRES_DATABASE=
POSTGRES_HOST=
POSTGRES_PASSWORD=
POSTGRES_PRISMA_URL=
POSTGRES_URL=
POSTGRES_URL_NON_POOLING=
POSTGRES_URL_NO_SSL=
POSTGRES_USER=

# Sentry https://sentry.io/
# @see https://docs.sentry.io/cli/configuration/
SENTRY_AUTH_TOKEN=
Expand Down Expand Up @@ -73,15 +97,8 @@ SMTP_PASS=
# Email Debug Mode (set "true" to skip sending emails and show debug output)
SEND_EMAIL_DEBUG=1


# Internal User Configuration
# Email domain for internal users (e.g., example.com)
# When set, users with matching email domain are treated as internal users.
# Note: Only exact domain matches are considered (subdomains are not matched).
INTERNAL_USER_EMAIL_DOMAIN=

# ---
# for development only
# ---
# GITHUB_APP_CLIENT_ID=
# GITHUB_APP_CLIENT_SECRET=