Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

add a how-to for self-hosted edge functions

Andrey A.b5cb4548b61c
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index dfbd3ef9d71..6fca567215c 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2840,10 +2840,11 @@ export const self_hosting: NavMenuConstant = {
{
name: 'How-to Guides',
items: [
- { name: 'Enabling MCP server', url: '/guides/self-hosting/enable-mcp' },
+ { name: 'Self-Hosted Functions', url: '/guides/self-hosting/self-hosted-functions' },
{ name: 'Restore from Platform', url: '/guides/self-hosting/restore-from-platform' },
{ name: 'Configure S3 Storage', url: '/guides/self-hosting/self-hosted-s3' },
{ name: 'Copy Storage from Platform', url: '/guides/self-hosting/copy-from-platform-s3' },
+ { name: 'Enabling MCP server', url: '/guides/self-hosting/enable-mcp' },
],
},
{
@@ -2896,6 +2897,11 @@ export const self_hosting: NavMenuConstant = {
url: '/reference/self-hosting-functions/introduction',
items: [],
},
+ {
+ name: 'Guide',
+ url: '/guides/self-hosting/self-hosted-functions',
+ items: [],
+ },
],
},
],
diff --git a/apps/docs/content/guides/self-hosting/self-hosted-functions.mdx b/apps/docs/content/guides/self-hosting/self-hosted-functions.mdx
new file mode 100644
index 00000000000..f8707dc48ac
--- /dev/null
+++ b/apps/docs/content/guides/self-hosting/self-hosted-functions.mdx
@@ -0,0 +1,239 @@
+---
+title: 'Self-Hosted Functions'
+description: 'Run and manage Edge Functions in your self-hosted Supabase instance.'
+subtitle: 'Run and manage Edge Functions in your self-hosted Supabase instance.'
+---
+
+Edge Functions work out of the box in a self-hosted Supabase setup. The `functions` service, API gateway routing, and a `hello` example function are all [pre-configured](https://github.com/supabase/supabase/tree/master/docker).
+
+<Admonition type="note">
+
+On managed Supabase platform, Edge Functions are deployed across multiple regions. Self-hosted standalone instance configuration resembles a standard serverless setup.
+
+</Admonition>
+
+## Invoke the default function
+
+The default `hello` function is located at `volumes/functions/hello/index.ts`. You can invoke it immediately after starting your stack:
+
+```bash
+curl http://<your-domain>:8000/functions/v1/hello
+```
+
+This returns `"Hello from Edge Functions!"`.
+
+## Create a new function
+
+### Step 1: Create a new directory with an `index.ts` file in `volumes/functions/`:
+
+```
+mkdir -p volumes/functions/my-function &&
+touch volumes/functions/my-function/index.ts
+```
+
+add the following code to `index.ts`:
+
+```typescript
+Deno.serve(async (req: Request) => {
+ const { name } = await req.json()
+ const message = `Hello, ${name}!`
+
+ return new Response(JSON.stringify({ message }), {
+ headers: { 'Content-Type': 'application/json' },
+ })
+})
+```
+
+### Step 2: Restart the functions service to pick up the new function:
+
+```bash
+docker compose restart functions --no-deps
+```
+
+### Step 3: Invoke your function:
+
+```bash
+curl -X POST http://<your-domain>:8000/functions/v1/my-function \
+ -H 'Content-Type: application/json' \
+ -d '{"name": "World"}'
+```
+
+You should be able to see the response from `my-function`:
+
+```
+{"message":"Hello, World!"}
+```
+
+## Custom environment variables
+
+### Using an env file (recommended)
+
+For multiple variables or secrets, create a separate env file, e.g., `.env.functions` in your `docker/` directory:
+
+```bash
+MY_CUSTOM_VAR=some-value
+```
+
+Add `env_file` to the `functions` service in `docker-compose.yml` (variables in `env_file` load first, then `environment` values take precedence):
+
+```yaml
+functions:
+ env_file:
+ - .env.functions
+ environment:
+ JWT_SECRET: ${JWT_SECRET}
+ SUPABASE_URL: http://kong:8000
+```
+
+<Admonition type="caution">
+
+Don't commit `.env.functions` to version control if it contains secrets. Add it to your `.gitignore`.
+
+</Admonition>
+
+Restart the functions service:
+
+```bash
+docker compose up -d --force-recreate --no-deps functions
+```
+
+### Using inline environment variables
+
+For one or two variables, you can add them directly under `environment` in `docker-compose.yml`:
+
+```yaml
+functions:
+ environment:
+ # Custom variables
+ MY_CUSTOM_VAR: ${MY_CUSTOM_VAR}
+ # Required variables
+ JWT_SECRET: ${JWT_SECRET}
+ SUPABASE_URL: http://kong:8000
+```
+
+Then define `MY_CUSTOM_VAR` in your main `.env` file, or specify the value directly.
+
+### Accessing variables in functions
+
+All container environment variables are forwarded to function workers by `main/index.ts`. Access them with:
+
+```typescript
+const customVar = Deno.env.get('MY_CUSTOM_VAR')
+```
+
+## Calling Supabase services from functions
+
+The functions service is pre-configured with the following environment variables:
+
+| Variable | Value | Purpose |
+| --- | --- | --- |
+| `SUPABASE_URL` | `http://kong:8000` | Internal API gateway URL |
+| `SUPABASE_PUBLIC_URL` | `http://<your-domain>:8000` | Base URL for accessing Supabase from the Internet |
+| `JWT_SECRET` | Your secret key | Legacy symmetric encryption key used to sign and verify JWTs |
+| `SUPABASE_ANON_KEY` | Your anon key | Client-side API key with limited permissions (`anon` role). |
+| `SUPABASE_SERVICE_ROLE_KEY` | Your service role key | Server-side API key with full database access (`service_role` role) |
+| `SUPABASE_DB_URL` | Postgres connection string | Can be used for direct database access |
+
+Here's an example function that queries a table using `@supabase/supabase-js`:
+
+```typescript
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+Deno.serve(async () => {
+ const supabase = createClient(
+ Deno.env.get('SUPABASE_URL')!,
+ Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+ )
+
+ const { data, error } = await supabase.from('todos').select('*')
+
+ return new Response(JSON.stringify({ data, error }), {
+ headers: { 'Content-Type': 'application/json' },
+ })
+})
+```
+
+### Internal vs external URLs
+
+This is a key distinction that affects how you build URLs in your functions:
+
+- **`SUPABASE_URL`** contains an internal Docker network hostname. Use it for server-side calls from your functions to other Supabase services (Auth, Storage, database via PostgREST). This is what the Supabase JS client should use inside functions.
+
+- **`SUPABASE_PUBLIC_URL`** is the externally-reachable URL of your Supabase instance (e.g., `<your-domain>:8000`). Use it if your function needs to build URLs that HTTP clients can reach from the outside.
+
+## Managing functions via dashboard
+
+Self-hosted Studio [mounts](https://github.com/supabase/supabase/blob/df8729a82b1847e2989c14ede27965612761d503/docker/docker-compose.yml#L66) the same `volumes/functions` directory as the functions service. You can check what functions are available using **Edge Functions** > **Functions** UI.
+
+## Deploying functions to a remote server
+
+To deploy a function to a remote server running self-hosted Supabase, copy the function directory with `scp`:
+
+```bash
+scp -r ./my-function user@<your-domain>:/path/to/self-hosted/volumes/functions/
+```
+
+Then restart the functions service on the remote host:
+
+```bash
+ssh user@<your-domain> 'cd /path/to/self-hosted && docker compose restart functions --no-deps'
+```
+
+## Copying functions from Supabase platform
+
+If you have existing functions on Supabase platform, you can download them and run them on your self-hosted instance. There are two ways to get the function source code:
+
+- **Dashboard** - open the function details in Dashboard and click **Download**.
+- **Local development & CLI** - run `supabase functions download <function-name> --project-ref <ref>` to download the source.
+
+Use `scp` to copy the function into `volumes/functions/<function-name>/` on your self-hosted instance, then restart the functions service.
+
+For more details, see:
+
+- [Quick start - Download edge functions](/docs/guides/functions/quickstart-dashboard#download-edge-functions)
+- [CLI commands - Download a function](/docs/reference/cli/supabase-functions-download)
+
+## Troubleshooting
+
+### 400 "missing function name in request"
+
+The request URL must include the function name after `/functions/v1/`. For example, `/functions/v1/hello` — not just `/functions/v1/`.
+
+### 500 error on invocation
+
+Check the functions service logs:
+
+```bash
+docker compose logs functions
+```
+
+Common causes: syntax errors in your function code, invalid imports, or missing dependencies.
+
+### 401 "invalid JWT"
+
+- Check that `FUNCTIONS_VERIFY_JWT` matches your intent (`true` or `false`) in `.env`
+- If verification is enabled, ensure you're passing a valid token: `Authorization: Bearer <anon_key or service_role_key>`
+
+### Changes to function code not reflected after editing
+
+Restart the functions service:
+
+```bash
+docker compose restart functions --no-deps
+```
+
+### Custom env vars not available in functions
+
+- Verify the variable is defined in `docker-compose.yml` (under `env_file` or `environment`)
+- Recreate the functions container after changing configuration
+- Check that the variable name matches exactly (case-sensitive)
+
+Use the following command to recreate the container, not just `restart`:
+
+```bash
+docker compose up -d --force-recreate --no-deps functions
+```
+
+### Memory or timeout errors
+
+The default limits are 150 MB memory and 60 seconds timeout per function invocation. These are set in `volumes/functions/main/index.ts`. To adjust them, edit the `memoryLimitMb` and `workerTimeoutMs` values and restart the functions service.
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index fc6dcb3729f..0fc499912b3 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -349,6 +349,7 @@ services:
environment:
JWT_SECRET: ${JWT_SECRET}
SUPABASE_URL: http://kong:8000
+ SUPABASE_PUBLIC_URL: ${SUPABASE_PUBLIC_URL}
SUPABASE_ANON_KEY: ${ANON_KEY}
SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
SUPABASE_DB_URL: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}