How to Run Self-Hosted Supabase Docker Container

Want full control of your backend? Learn how to run a self-hosted Supabase Docker container step-by-step. Unlock powerful features—Postgres, Auth, Storage & Edge Functions—on your own server. Don’t get left behind, start hosting Supabase today! #centlinux #linux #docker

Introduction

Supabase has quickly risen as one of the most popular open-source backends for developers who want the power of PostgreSQL combined with modern developer-friendly tools. Often called the “open-source Firebase alternative,” it gives you authentication, real-time data, storage, and serverless functions in one stack. While many developers rely on the hosted version of Supabase, running your own self-hosted instance provides complete control, cost savings, and enhanced security.

But here’s the question: how do you actually self-host Supabase? The answer is Docker. With Docker, you can containerize Supabase and run it on your local machine or server. This guide will walk you step by step through everything you need—from prerequisites to setup, configuration, and production deployment—so you can confidently run your own Supabase instance using Docker.

Understanding Supabase and Its Core Features

Before diving into the technical setup, let’s get a clear picture of what Supabase really offers. At its core, Supabase is an open-source alternative to Firebase, but instead of being built on proprietary infrastructure, it is powered by PostgreSQL. That means you’re not locked into a vendor, and you benefit from all the maturity, scalability, and flexibility of one of the most powerful databases in the world.

Here are the key components that make Supabase stand out:

1. Database (PostgreSQL): A production-ready, relational database with support for real-time updates.
2. Authentication: Secure and customizable user authentication, supporting email, magic links, and third-party logins.
3. Storage: Object storage for images, videos, and files with fine-grained access control.
4. Edge Functions: Serverless functions that run close to the user, making API calls fast and efficient.

Developers prefer Supabase because it’s open-source, self-hostable, and developer-friendly. Unlike Firebase, you can own your data and infrastructure. This flexibility is why many startups and enterprises choose to self-host Supabase rather than relying solely on its hosted version.

Prerequisites to Run Supabase Docker Container

Before you start spinning up containers, you need to prepare your system. Running Supabase requires some baseline software and hardware.

System Requirements

• CPU: Minimum 2 cores (4+ recommended for production)
• RAM: At least 4 GB (8 GB+ recommended for larger projects)
• Disk Space: 10 GB+ free space depending on database size and storage needs

Software Requirements

1. Docker: Supabase services are packaged in containers. Install the latest version of Docker for your operating system.
2. Docker Compose: Required for orchestrating multiple containers (Postgres, API, Auth, Studio, etc.) in one setup.
3. Git: To clone the official Supabase repository.
4. Text Editor (e.g., VS Code): For editing configuration files like .env.

Environment Setup

• Update your operating system to the latest version.
• Ensure that Docker Desktop (on Windows/macOS) or Docker Engine (on Linux) is running.
• Test Docker installation with:
  • docker --version
  • docker-compose --version
• Optional but recommended: Install Node.js if you plan to use the Supabase CLI later.

Having these prerequisites in place ensures a smooth setup and avoids errors when running your Supabase containers.

Recommended Training: Docker Mastery: with Kubernetes +Swarm from a Docker Captain

Setting Up the Supabase Repository

Once your system is ready, it’s time to get Supabase running locally. The official Supabase team provides a Docker Compose setup that makes this process straightforward.

Step 1: Clone the Repository

Run the following command to clone the Supabase self-host repo:

git clone https://github.com/supabase/supabase
cd supabase/docker

Step 2: Explore the Folder Structure

Inside the docker directory, you’ll find files like:

• docker-compose.yml – Defines all the containers (Postgres, API, Studio, etc.).
• .env.example – Example environment variables to configure your setup.
• volumes/ – A directory where persistent data will be stored.

Understanding this structure is important, as most of your customization will happen here.

Step 3: Copy and Edit Environment File

Copy the example environment file:

cp .env.example .env

This .env file holds critical variables like database passwords and JWT secrets, which we’ll configure in the next section.

Configuring Environment Variables

The .env file is the backbone of your self-hosted Supabase instance. It contains secrets and settings that dictate how your containers interact with each other.

Key Variables You Must Configure

1. JWT_SECRET
   • Used for signing authentication tokens.
   • Must be a long, random string for security.
   • Example: export JWT_SECRET=mySuperSecretRandomKey123
2. POSTGRES_PASSWORD
   • Password for the PostgreSQL database.
   • Choose something strong and secure.
3. API Keys
   • Supabase generates both anon (public) and service_role (admin-level) keys.
   • These will be used by your applications to connect to Supabase.
4. Storage & URL Settings
   • Configure bucket storage paths.
   • Set your domain if deploying on a server.

Best Practices for Environment Setup

• Never commit .env to version control.
• Use a password manager or vault to store secrets.
• For production, rotate JWT secrets periodically.
• If hosting on a VPS or cloud provider, ensure .env is secured with proper file permissions.

Once configured, your Supabase setup is ready to launch. The next step is starting the containers with Docker Compose.

Apple AirTag 4 Pack. Keep Track of and find Your Keys, Wallet, Luggage, Backpack, and More. Simple one-tap Set up with iPhone or iPad

(48529485)

29% Off $99.00 $69.99 (as of August 28, 2025 14:49 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

Keep track of and find your items alongside friends and devices in the Find My app Key finder and locator for your wallet, luggage, backpack, and more. Share an AirTag with up to 5 people, so items that everyone uses can be tracked by friends and fam… read more

Running Supabase with Docker Compose

Now comes the exciting part—actually running Supabase on your machine. Docker Compose makes this a single command process.

Step 1: Start the Containers

In the docker directory, run:

docker-compose up -d

This command pulls the necessary images, creates containers, and runs them in the background.

Step 2: Verify the Containers

Check if everything is running:

docker ps

You should see containers for:

• PostgreSQL
• API
• Authentication
• Realtime
• Studio (dashboard)

Step 3: Access Supabase Studio

Open your browser and go to:

http://localhost:3000

Supabase Studio should now be live, allowing you to manage your database, authentication, and storage visually.

If everything is working, congratulations—you’ve successfully launched your own self-hosted Supabase instance with Docker!

Managing Supabase Containers

Once you’ve successfully launched Supabase with Docker Compose, you’ll need to know how to manage it. Running the containers is just the beginning—real-world usage involves stopping, restarting, updating, and sometimes scaling services depending on your needs.

Starting and Stopping Containers

To start your Supabase instance:

docker-compose up -d

To stop it:

docker-compose down

If you just want to restart:

docker-compose restart

Using these commands, you can control the entire stack with a single action. Docker Compose ensures all services restart together and remain linked.

Updating Supabase

Supabase is under active development, so updates are frequent. To update:

Stop your containers:

docker-compose down

Pull the latest images:

docker-compose pull

Restart services:

docker-compose up -d

Scaling Services

In certain situations—like high traffic on the API—you might want to run multiple instances of a service. With Docker Compose, you can do this:

docker-compose up -d --scale api=3

This command launches three instances of the API service, helping distribute the load.

Managing containers effectively ensures your Supabase setup runs smoothly and is always up to date.

Persisting Data in Volumes

One of the most important things when self-hosting Supabase is making sure your data doesn’t vanish when containers are restarted. By default, containers are ephemeral—if you remove them, data is lost. That’s where volumes come into play.

Why Volumes Are Crucial

• Persistence: Your PostgreSQL database and storage buckets must survive restarts.
• Backups: Volumes make it easier to back up and restore data.
• Flexibility: You can move data between servers if needed.

Mapping Volumes

In your docker-compose.yml, you’ll see volume mappings like:

volumes:
  - ./volumes/db:/var/lib/postgresql/data
  - ./volumes/storage:/var/lib/storage

This means all database files are stored in the ./volumes/db directory on your host machine, not inside the container.

Backup and Restore

To back up your PostgreSQL data, run:

docker exec -t <postgres_container> pg_dumpall -c -U postgres > backup.sql

To restore from a backup:

cat backup.sql | docker exec -i <postgres_container> psql -U postgres

By using volumes properly, you ensure your self-hosted Supabase setup is reliable and disaster-proof.

Setting Up Reverse Proxy & SSL

If you’re hosting Supabase on a VPS or dedicated server, you don’t want users connecting via http://ip:port. Instead, you’ll want a domain name with SSL (HTTPS) enabled.

Why Use a Reverse Proxy?

A reverse proxy like Nginx or Traefik helps by:

• Handling domain name routing.
• Enabling HTTPS encryption with Let’s Encrypt.
• Improving security and performance.
• Allowing multiple services to run on one server.

Example with Nginx

You can configure an Nginx reverse proxy with a config like:

server {
    listen 80;
    server_name supabase.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Enable SSL

For automatic SSL certificates, use Certbot:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d supabase.example.com

Now your Supabase Studio and API endpoints will be available securely at https://supabase.example.com.

Brooks Women’s Ghost 16 Neutral Running Shoe

(4655508)

32% Off $139.95 $93.95 (as of August 28, 2025 16:12 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

THIS WOMEN'S SHOE IS FOR: Runners looking for a smooth ride that won’t distract from the fun of the run. The Ghost 16 offers a refined 3D Fit Print to create a more seamless, secure fit. This Brooks Ghost 16 is a certified PDAC A5500 Diabetic shoe an… read more

Using Supabase CLI for Management

While Docker Compose handles containers, the Supabase CLI adds extra functionality for developers managing Supabase projects.

Installing Supabase CLI

You can install it via npm:

npm install -g supabase

Or download prebuilt binaries from the official Supabase GitHub.

Managing Local Projects

With the CLI, you can:

Initialize a new Supabase project:

supabase init

Start a local project (using Docker in the background):

supabase start

Stop the project:

supabase stop

Deployment Workflows

The CLI also helps in managing migrations, seeding databases, and deploying edge functions. It’s especially useful for teams that want smooth CI/CD integration with Supabase.

By combining Docker and the CLI, you gain complete control over your local and production Supabase instances.

Customizing Authentication and Roles

Supabase authentication is flexible, but when self-hosting, you’ll likely want to customize it for your project.

Configuring JWT Secrets

The JWT_SECRET in your .env file ensures tokens are securely signed. You can adjust token expiration and rotation policies for added security.

Managing Roles in PostgreSQL

Supabase relies heavily on PostgreSQL’s role-based access control. Common roles include:

• anon: Minimal access, used for unauthenticated users.
• authenticated: Assigned to logged-in users.
• service_role: Full admin access, used internally.

You can create custom roles for advanced use cases, e.g., read-only users or limited write access.

Third-Party Authentication Providers

Supabase supports providers like Google, GitHub, and Apple. To enable them:

• Add API keys in your .env.
• Configure redirect URLs in your app.
• Enable providers in Supabase Studio under “Authentication.”

With proper role management and authentication setup, your Supabase instance becomes secure and production-ready.

Deploying Edge Functions

One of Supabase’s most powerful features is Edge Functions—serverless functions that run close to your users for maximum speed and efficiency. When self-hosting with Docker, you can still take advantage of this feature.

What Are Edge Functions?

Edge Functions allow you to:

• Run backend logic without maintaining a dedicated server.
• Securely extend Supabase with custom endpoints.
• Handle real-time events, API requests, or background jobs.

Think of them like AWS Lambda or Vercel Functions but tightly integrated with Supabase.

Creating a Sample Function

Install Supabase CLI (if not already):

npm install -g supabase

Create a new function:

supabase functions new hello

This generates a starter function in supabase/functions/hello/index.ts.

Edit the function code (example: return a greeting):

export default async (req, res) => {
  return res.json({
    message: "Hello from Supabase Edge Function!"
  });
};

Deploying Edge Functions

Deploying is simple:

supabase functions deploy hello

You can now call your function via an API request:

POST https://<your-domain>.supabase.co/functions/v1/hello

Managing Functions with Docker

When using Docker, ensure the functions service is enabled in your docker-compose.yml. This ensures functions are built and deployed alongside your stack.

By leveraging Edge Functions, you extend Supabase beyond just a database and authentication provider—it becomes a full backend platform.

Monitoring and Logging

Running a self-hosted Supabase instance means you are responsible for keeping it healthy. Monitoring and logging help you track performance, troubleshoot issues, and ensure uptime.

Viewing Docker Logs

Each Supabase service runs as a Docker container, so logs can be accessed with:

docker logs <container_name>

For example, to check PostgreSQL logs:

docker logs supabase-db

Using Supabase Studio

Supabase Studio offers real-time insights into:

• Database queries
• User authentication events
• Storage usage
• Function execution

This makes it easy to spot performance bottlenecks or suspicious activity.

External Monitoring Tools

For advanced setups, integrate Supabase with:

• Prometheus + Grafana: For visual dashboards.
• Datadog or New Relic: Cloud monitoring solutions.
• Elastic Stack (ELK): Centralized logging and searching.

By combining Docker logs, Supabase Studio, and external tools, you gain full visibility over your infrastructure.

PINSPARK Men Crewneck Sweatshirt Lightweight Long Sleeve Running Sweat Shirts Casual Pullover Tops with Zipper Pocket

(43520)

$19.99 (as of August 28, 2025 14:40 GMT +00:00 – More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

【High Quality Fabric】 Our running sweatshirts are made of high quality fabric, which are lightweight, soft, comfortable, breathable, with enough stretch, giving you a super great wearing experience, perfect for spring, fall or winter. 【Side Zipper Po… read more

Common Issues and Troubleshooting

Even with the best setup, things can go wrong. Let’s cover some common issues when running Supabase Docker container.

1. Docker Compose Fails to Start

• Cause: Port conflicts or outdated Docker.
• Fix: Make sure ports (e.g., 5432 for PostgreSQL, 3000 for Studio) are not already in use. Update Docker with:

docker-compose pull

2. Database Connection Issues

• Cause: Wrong credentials in .env.
• Fix: Check POSTGRES_PASSWORD and DATABASE_URL settings. Restart containers after fixing.

3. Authentication Errors

• Cause: Incorrect JWT_SECRET or expired tokens.
• Fix: Update your .env with a valid secret and restart containers.

4. Supabase Studio Not Loading

• Cause: Reverse proxy misconfiguration.
• Fix: Verify your Nginx or Traefik setup. Ensure ports are forwarded correctly.

5. Slow Performance

• Cause: Low server resources.
• Fix: Allocate more RAM/CPU or scale services using:

docker-compose up -d --scale api=3

By documenting solutions to these issues, you’ll save time and frustration when things break.

Best Practices for Production Deployment

If you’re self-hosting Supabase for production use, you’ll want to follow some best practices to ensure security, reliability, and scalability.

1. Security Hardening

• Change all default passwords (Postgres, JWT, etc.).
• Use HTTPS everywhere with Let’s Encrypt or another SSL provider.
• Restrict access to the database—expose only necessary ports.

2. Backup Strategies

• Automate PostgreSQL backups with pg_dump.
• Backup storage buckets regularly.
• Test restoration procedures before going live.

3. Monitoring & Alerts

• Use Prometheus/Grafana for real-time monitoring.
• Set up email or Slack alerts for downtime or errors.

4. Scaling for Traffic

• Scale API services horizontally with Docker Compose or Kubernetes.
• Use a load balancer for distributing requests.
• Consider separating database and API services across servers.

5. Regular Updates

Pull the latest Docker images monthly:

docker-compose pull && docker-compose up -d

Keep your OS and Docker engine patched.

Following these best practices ensures your self-hosted Supabase is stable and secure, even under heavy load.

Conclusion

Running Supabase in a self-hosted Docker environment gives you the power of a modern backend without relying on third-party hosting. You now know how to:

• Set up Supabase with Docker Compose.
• Configure .env for authentication and database access.
• Manage containers, volumes, and backups.
• Secure your instance with SSL and reverse proxy.
• Deploy Edge Functions and monitor performance.

Self-hosting Supabase puts you in control—of your data, your infrastructure, and your costs. Whether for development, staging, or production, Docker makes it simple to run Supabase anywhere.

Optimize your cloud infrastructure and secure your servers with my AWS and Linux administration services. Let’s ensure your systems run smoothly. Connect with me now! if you need any guidance or advice related to your Linux VPS.

FAQs

1. Can I run Supabase without Docker?
Yes, but it’s far more complex. Docker bundles all services (Postgres, API, Auth, etc.) into containers, making it much easier to run.

2. How do I update my Supabase instance?
Stop containers, pull new images, and restart:

docker-compose down
docker-compose pull
docker-compose up -d

3. Is self-hosted Supabase production-ready?
Yes, but you must handle security, backups, and scaling yourself. The cloud-hosted Supabase automates these, but self-hosting gives full control.

4. Can I use Kubernetes instead of Docker Compose?
Absolutely. Many teams deploy Supabase on Kubernetes for advanced scaling and orchestration.

5. What are the main differences between Supabase Cloud and self-hosted?

• Cloud: Managed, secure, automatic updates, less hassle.
• Self-hosted: Full control, lower cost, customizable, but requires more maintenance.