The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.tsindex 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.mdxnew file mode 100644index 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.ymlindex 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}