Repository: neondatabase/website
Pull request #3372: docs: add neon local docs page - first pass
Author: login: PaulieScanlon
Created: 2025-04-22T14:41:14Z | Merged: 2025-04-28T16:05:59Z

- create docs page
- add image directory

@danieltprice: Can you advise on where to create this page and if the image folder is correctly located, please?

@jeff-at-neon: Can you give this a thorough review, please?  


Diff:
diff --git a/content/docs/local/neon-local.md b/content/docs/local/neon-local.md
new file mode 100644
index 0000000000..a27bde2e1a
--- /dev/null
+++ b/content/docs/local/neon-local.md
@@ -0,0 +1,131 @@
+---
+title: Neon Local
+enableTableOfContents: true
+subtitle: Use Docker environments to connect to Neon and manage branches automatically
+updatedOn: '2025-04-22T22:55:27.453Z'
+---
+
+[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. By default, it automatically creates a new database branch when the container starts and deletes it when the container stops.
+
+Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.
+
+## Docker compose instructions
+
+You can add the Neon Local by adding the following to your `docker-compose.yml` file.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: serverless
+```
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: postgres
+```
+
+</CodeTabs>
+
+## Docker run instructions
+
+You can also run the Neon Local container with the following Docker run command.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=serverless \
+  neondatabase/neon_local:latest
+```
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=postgres \
+  neondatabase/neon_local:latest
+```
+
+</CodeTabs>
+
+## Connect
+
+Connect using either the Neon [serverless driver](/serverless/serverless-driver) or any other Postgres client.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```javascript
+import { neon, neonConfig } from '@neondatabase/serverless';
+neonConfig.fetchEndpoint = 'http://db:5432/sql';
+
+const sql = neon('postgres://neon:npg@db:5432/neondb');
+```
+
+```javascript
+import pg from 'pg';
+const { Pool } = pg;
+const connectionString = 'postgres://neon:npg@db:5432/neondb?sslmode=no-verify';
+
+const pool = new Pool({ connectionString });
+```
+
+</CodeTabs>
+
+## Configuration options
+
+| Key                | Configuration                                                                                  | Required | Default    |
+| ------------------ | ---------------------------------------------------------------------------------------------- | -------- | ---------- |
+| `NEON_API_KEY`     | Generate a Neon API key by following instructions at: [Manage API Keys](/docs/manage/api-keys) | Yes      | n/a        |
+| `NEON_PROJECT_ID`  | Your project ID, found in the Neon console under **Settings** > **General**                    | Yes      | n/a        |
+| `DRIVER`           | The type of database driver. Options: `serverless` or `postgres`                               | No       | `postgres` |
+| `PARENT_BRANCH_ID` | The parent branch to use when creating a local child branch.                                   | No       | `main`     |
+| `DELETE_BRANCH`    | Whether to delete the branch when the container stops. Options: `true` or `false`              | No       | `true`     |
+
+## Persistent Neon Branch per Git Branch
+
+If you want Neon Local to create a branch that matches your Git branch, provide two volume mounts:
+
+1. A mount that persists Neon branch metadata within your project
+2. A mount that exposes the current Git branch name
+
+<Admonition type="note">
+This will automatically create a `.neon_local` folder in your project to store branch metadata. Be sure to add this folder to your `.gitignore` to avoid committing database connection information to version control.
+</Admonition>
+
+```yml
+db:
+  image: neondatabase/neon_local:latest
+  ports:
+    - '5432:5432'
+  environment:
+    NEON_API_KEY: ${NEON_API_KEY}
+    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+  volumes:
+    - ./.neon_local/:/tmp/.neon_local
+    - ./.git/HEAD:/tmp/.git/HEAD:ro,consistent
+```
+
+## Git integration using Docker on Mac
+
+If using Docker Desktop for Mac, make sure that your Virtual Machine is set to use gRPC FUSE, not VirtioFS. This allows Neon Local to detect git branch changes. There is currently a bug with VirtioFS that can prevent containers from being properly updated when local files change while the container is running.
+
+![Docker Desktop are set to gRPC FUSE](/docs/local/neon-local-docker-settings.jpg)
diff --git a/content/docs/sidebar.yaml b/content/docs/sidebar.yaml
index 94d63d4d2a..916df405a4 100644
--- a/content/docs/sidebar.yaml
+++ b/content/docs/sidebar.yaml
@@ -386,10 +386,10 @@
         - section: Updates
           items:
             - title: Overview
-              slug: manage/maintenance-updates-overview              
+              slug: manage/maintenance-updates-overview
               tag: new
             - title: Platform maintenance
-              slug: manage/platform-maintenance              
+              slug: manage/platform-maintenance
               tag: new
             - title: Updates
               slug: manage/updates
@@ -924,6 +924,10 @@
               slug: guides/neon-twin-full-pg-dump-restore
             - title: Partial Twin
               slug: guides/neon-twin-partial-pg-dump-restore
+    - title: Neon Local
+      icon: container
+      tag: new
+      slug: local/neon-local
 - section: Postgres
   items:
     - title: PostgreSQL Tutorial
diff --git a/public/docs/local/neon-local-docker-settings.jpg b/public/docs/local/neon-local-docker-settings.jpg
new file mode 100644
index 0000000000..342a0c24b0
Binary files /dev/null and b/public/docs/local/neon-local-docker-settings.jpg differ
diff --git a/src/components/pages/doc/menu/icon/icon.jsx b/src/components/pages/doc/menu/icon/icon.jsx
index bd3eece9cf..a8e0e356bd 100644
--- a/src/components/pages/doc/menu/icon/icon.jsx
+++ b/src/components/pages/doc/menu/icon/icon.jsx
@@ -12,6 +12,7 @@ import ChangelogIcon from 'icons/docs/sidebar/changelog.inline.svg';
 import CliIcon from 'icons/docs/sidebar/cli.inline.svg';
 import CommunityIcon from 'icons/docs/sidebar/community.inline.svg';
 import ConnectIcon from 'icons/docs/sidebar/connect.inline.svg';
+import ContainerIcon from 'icons/docs/sidebar/container.inline.svg';
 import DocsIcon from 'icons/docs/sidebar/docs.inline.svg';
 import ExtensionIcon from 'icons/docs/sidebar/extension.inline.svg';
 import FeaturesIcon from 'icons/docs/sidebar/features.inline.svg';
@@ -61,6 +62,7 @@ const icons = {
   cli: CliIcon,
   community: CommunityIcon,
   connect: ConnectIcon,
+  container: ContainerIcon,
   docs: DocsIcon,
   extension: ExtensionIcon,
   features: FeaturesIcon,
diff --git a/src/icons/docs/sidebar/container.inline.svg b/src/icons/docs/sidebar/container.inline.svg
new file mode 100644
index 0000000000..d345580eb4
--- /dev/null
+++ b/src/icons/docs/sidebar/container.inline.svg
@@ -0,0 +1,7 @@
+<svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M15.5947 6.1838C15.5947 5.79084 15.3327 5.39788 15.0708 5.2014L10.9447 2.64717C10.775 2.55071 10.5832 2.5 10.388 2.5C10.1928 2.5 10.001 2.55071 9.83132 2.64717L3.08553 6.57675C2.75807 6.70774 2.49609 7.1007 2.49609 7.49366V11.8162C2.49609 12.1437 2.75807 12.6021 3.02004 12.7986L7.14611 15.3528C7.31579 15.4493 7.50762 15.5 7.7028 15.5C7.89798 15.5 8.08981 15.4493 8.25949 15.3528L15.0053 11.4232C15.3327 11.2268 15.5947 10.7683 15.5947 10.4408V6.1838Z" stroke="#C9CBCF" stroke-width="0.873242" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M7.7345 15.4842V10.3102L2.56055 7.10107" stroke="#C9CBCF" stroke-width="0.873242" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M7.73535 10.31L15.529 5.79102" stroke="#C9CBCF" stroke-width="0.873242" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M10.3555 14.1084V8.80347" stroke="#C9CBCF" stroke-width="0.873242" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M12.9756 12.6018V7.29688" stroke="#C9CBCF" stroke-width="0.873242" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>


Reviews:
user: login: PaulieScanlon
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-22T14:51:34Z
user: login: PaulieScanlon
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T17:55:17Z
user: login: jeff-at-neon
body: This all looks great to me.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-28T13:53:00Z
user: login: bgrenon
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-28T16:01:18Z

Review comments:
diff_hunk: @@ -0,0 +1,116 @@
+---
+title: Neon Local
+enableTableOfContents: true
+subtitle: Connect to Neon using Docker containers
+updatedOn: '2025-04-22T22:55:27.453Z'
+---
+
+[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. By default, it automatically creates a new database branch when the container starts and deletes it when the container stops.
+
+Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.
+
+## Docker compose instructions
+
+You can add the Neon Local by adding the following to your `docker-compose.yml` file.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: serverless
+```
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: postgres
+```
+
+</CodeTabs>
+
+## Docker run instructions
+
+You can also run the Neon Local container with the following Docker run command.
+
+```shell
+$ docker run \
+    -name db
+    -p 5432:5432
+    -e NEON_API_KEY: <neon_api_key>
+    -e NEON_PROJECT_ID: <neon_project_id>
+    neondatabase/neon_local:latest
path: content/docs/local/neon-local.md
user: login: PaulieScanlon
body: Should there be `-e DRIVER: postgress` and `-e DRIVER: serverless` code snippets, as i've done for the compose example?
created_at: 2025-04-22T14:51:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Neon Local
+enableTableOfContents: true
+subtitle: Connect to Neon using Docker containers
+updatedOn: '2025-04-22T22:55:27.453Z'
+---
+
+[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. By default, it automatically creates a new database branch when the container starts and deletes it when the container stops.
+
+Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.
+
+## Docker compose instructions
+
+You can add the Neon Local by adding the following to your `docker-compose.yml` file.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: serverless
+```
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: postgres
+```
+
+</CodeTabs>
+
+## Docker run instructions
+
+You can also run the Neon Local container with the following Docker run command.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=serverless \
+  neondatabase/neon_local:latest
+```
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=postgres \
+  neondatabase/neon_local:latest
+```
+
+</CodeTabs>
+
+## Connect
+
+Connect using either the Neon [serverless driver](/serverless/serverless-driver) or any other Postgres client.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```javascript
+import { neon, neonConfig } from '@neondatabase/serverless';
+neonConfig.fetchEndpoint = 'http://db:5432/sql';
+
+const sql = neon('postgres://neon:npg@db:5432/neondb');
path: content/docs/local/neon-local.md
user: login: PaulieScanlon
body: @jeff-at-neon, I've just seen your comment on the blog post. is `no-verify` required wth the serverless driver. In my test app I only needed to add this to the `pg` version. But, if you wanna play it safe and add it to all snippets, that's fine with me.  
created_at: 2025-04-23T17:55:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Neon Local
+enableTableOfContents: true
+subtitle: Use Docker environments to connect to Neon and manage branches automatically
+updatedOn: '2025-04-22T22:55:27.453Z'
+---
+
+[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. By default, it automatically creates a new database branch when the container starts and deletes it when the container stops.
+
+Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.
+
+## Docker compose instructions
+
+You can add the Neon Local by adding the following to your `docker-compose.yml` file.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: serverless
+```
+
+```shell
+  db:
+    image: neondatabase/neon_local:latest
+    ports:
+      - '5432:5432'
+    environment:
+      NEON_API_KEY: ${NEON_API_KEY}
+      NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+      DRIVER: postgres
+```
+
+</CodeTabs>
+
+## Docker run instructions
+
+You can also run the Neon Local container with the following Docker run command.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=serverless \
+  neondatabase/neon_local:latest
+```
+
+```shell
+docker run \
+  --name db \
+  -p 5432:5432 \
+  -e NEON_API_KEY= <neon_api_key> \
+  -e NEON_PROJECT_ID=<neon_project_id> \
+  -e DRIVER=postgres \
+  neondatabase/neon_local:latest
+```
+
+</CodeTabs>
+
+## Connect
+
+Connect using either the Neon [serverless driver](/serverless/serverless-driver) or any other Postgres client.
+
+<CodeTabs labels={["Neon serverless driver", "node-postgres"]}>
+
+```javascript
+import { neon, neonConfig } from '@neondatabase/serverless';
+neonConfig.fetchEndpoint = 'http://db:5432/sql';
+
+const sql = neon('postgres://neon:npg@db:5432/neondb');
+```
+
+```javascript
+import pg from 'pg';
+const { Pool } = pg;
+const connectionString = 'postgres://neon:npg@db:5432/neondb?sslmode=no-verify';
+
+const pool = new Pool({ connectionString });
+```
+
+</CodeTabs>
+
+## Configuration options
+
+| Key                | Configuration                                                                                  | Required | Default    |
+| ------------------ | ---------------------------------------------------------------------------------------------- | -------- | ---------- |
+| `NEON_API_KEY`     | Generate a Neon API key by following instructions at: [Manage API Keys](/docs/manage/api-keys) | Yes      | n/a        |
+| `NEON_PROJECT_ID`  | Your project ID, found in the Neon console under **Settings** > **General**                    | Yes      | n/a        |
+| `DRIVER`           | The type of database driver. Options: `serverless` or `postgres`                               | No       | `postgres` |
+| `PARENT_BRANCH_ID` | The parent branch to use when creating a local child branch.                                   | No       | `main`     |
+| `DELETE_BRANCH`    | Whether to delete the branch when the container stops. Options: `true` or `false`              | No       | `true`     |
+
+## Persistent Neon Branch per Git Branch
+
+If you want Neon Local to create a branch that matches your Git branch, provide two volume mounts:
+
+1. A mount that persists Neon branch metadata within your project
+2. A mount that exposes the current Git branch name
+
+<Admonition type="note">
+This will automatically create a `.neon_local` folder in your project to store branch metadata. Be sure to add this folder to your `.gitignore` to avoid committing database connection information to version control.
+</Admonition>
+
+```yml
+db:
+  image: neondatabase/neon_local:latest
+  ports:
+    - '5432:5432'
+  environment:
+    NEON_API_KEY: ${NEON_API_KEY}
+    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
+  volumes:
+    - ./.neon_local/:/tmp/.neon_local
+    - ./.git/HEAD:/tmp/.git/HEAD:ro,consistent
+```
+
+## Git integration using Docker on Mac
+
+If using Docker Desktop for Mac, ensure that your Virtual Machine is set to use gRPC FUSE, not VirtioFS this allows Neon Local to detect git branch changes. There is currently a bug with VirtioFS which can prevent containers from being properly updated when local files change while the container is running.
path: content/docs/local/neon-local.md
user: login: bgrenon
body: ```suggestion
If using Docker Desktop for Mac, make sure that your Virtual Machine is set to use gRPC FUSE, not VirtioFS. This allows Neon Local to detect git branch changes. There is currently a bug with VirtioFS that can prevent containers from being properly updated when local files change while the container is running.
```
created_at: 2025-04-28T16:01:18Z
author_association: COLLABORATOR

PR comments:
user: login: vercel[bot]
created_at: 2025-04-22T14:41:19Z
body: [vc]: #41SfOwwX+qSKplrfo1If5nteJhlgm21Ex4CMH+RoBVE=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJuZW9uLW5leHQiLCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20vbmVvbmRhdGFiYXNlL25lb24tbmV4dC9HaUU4WGZTVEJrRlozQlJyOFZkNWRkZGF1bVFiIiwicHJldmlld1VybCI6Im5lb24tbmV4dC1naXQtZG9jcy1uZW9uLWxvY2FsLW5lb25kYXRhYmFzZS52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIiwibGl2ZUZlZWRiYWNrIjp7InJlc29sdmVkIjowLCJ1bnJlc29sdmVkIjowLCJ0b3RhbCI6MCwibGluayI6Im5lb24tbmV4dC1naXQtZG9jcy1uZW9uLWxvY2FsLW5lb25kYXRhYmFzZS52ZXJjZWwuYXBwIn0sInJvb3REaXJlY3RvcnkiOm51bGx9XX0=
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)

| Name | Status | Preview | Comments | Updated (UTC) |
| :--- | :----- | :------ | :------- | :------ |
| **neon-next** | ✅ Ready ([Inspect](https://vercel.com/neondatabase/neon-next/GiE8XfSTBkFZ3BRr8Vd5dddaumQb)) | [Visit Preview](https://neon-next-git-docs-neon-local-neondatabase.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/neon-next-git-docs-neon-local-neondatabase.vercel.app?via=pr-comment-feedback-link) | Apr 28, 2025 4:07pm |


author_association: NONE
user: login: danieltprice
created_at: 2025-04-23T22:33:32Z
body: > @danieltprice: Can you advise on where to create this page and if the image folder is correctly located, please?

@PaulieScanlon why don't we put it under Workflows in the sidebar, beneath Neon Twin. 
The image folder location is good. You could ask PP for a "Local development" icon.


author_association: COLLABORATOR
user: login: PaulieScanlon
created_at: 2025-04-24T08:40:58Z
body: Cool, thanks @danieltprice, I'll move the link and have opened a ticket with PP for the icon.
author_association: CONTRIBUTOR