Supabase on Ubuntu 22.04: A Step-by-Step Guide

Hey everyone! So, you’re looking to get Supabase up and running on your Ubuntu 22.04 machine, huh? Awesome choice! Supabase is a game-changer, offering an open-source Firebase alternative with tons of cool features like a PostgreSQL database, authentication, real-time subscriptions, and more. Setting it up on your own server, especially on Ubuntu 22.04 (which is Jammy Jellyfish, by the way – cool name!), can seem a bit daunting at first, but trust me, it’s totally manageable. We’re going to walk through this together, step-by-step, so you can have your own self-hosted Supabase instance humming in no time. This guide is designed to be super clear and easy to follow, even if you’re not a seasoned sysadmin. We’ll cover everything from prerequisites to the final launch, ensuring you understand each part of the process. By the end of this, you’ll be well on your way to leveraging the power of Supabase without relying on third-party managed services, giving you full control and flexibility over your backend infrastructure. Let’s dive in!

Getting Started: Prerequisites and System Updates

Alright guys, before we even think about installing Supabase, we need to make sure our Ubuntu 22.04 system is in tip-top shape. Think of this as prepping your kitchen before you start cooking a gourmet meal. First things first, you need to update your package lists and upgrade any existing packages. This ensures you have the latest security patches and software versions, which is super important for stability and security. Open up your terminal and type in these two commands:

sudo apt update
sudo apt upgrade -y

Give those a minute to run. The -y flag automatically says ‘yes’ to any prompts, making the process smoother. While that’s happening, let’s talk about what else you might need. You’ll definitely want to have curl installed, as we’ll be using it quite a bit. If you don’t have it, just run sudo apt install curl -y . Also, ensure you have Docker and Docker Compose installed. Supabase heavily relies on Docker containers for its various services. If you haven’t installed them yet, the official Docker documentation is your best friend. Generally, you’ll need to add the Docker GPG key, add the Docker repository to your sources list, and then install docker-ce , docker-ce-cli , and containerd.io . For Docker Compose, you can usually download the binary directly. Here’s a quick rundown of commands that often work, but always refer to the official Docker installation guide for Ubuntu for the most up-to-date instructions :

# Install Docker prerequisites
sudo apt update
sudo apt install 
    ca-certificates 
    curl 
    gnupg 
    lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository
echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu 
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# Install Docker Compose (check latest version on Docker Hub)
# Example for v2.x.x - adjust version as needed
LATEST_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d"\"" -f4)
sudo curl -L "https://github.com/docker/compose/releases/download/${LATEST_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

After installing Docker and Docker Compose, it’s a good idea to add your user to the docker group so you don’t have to use sudo for every Docker command. Just run sudo usermod -aG docker $USER and then log out and log back in for the changes to take effect. This is crucial, guys, don’t forget that logout/login step! Finally, let’s ensure Node.js and npm are installed. Supabase uses these for its CLI. You can usually install them via apt or use a version manager like nvm for more control. For a quick install via apt:

sudo apt install nodejs npm -y

If you need a newer version, nvm is the way to go. You can find installation instructions for nvm on its GitHub page. Basically, you’ll curl a script and then follow the instructions to add it to your shell profile.

Downloading and Configuring Supabase CLI

Now that our system is prepped and ready, it’s time to grab the Supabase CLI . This is your command-line interface for interacting with your Supabase instance. We’ll be installing it globally so you can access it from anywhere on your system. The easiest way to do this is via npm (Node Package Manager), which is why we made sure Node.js and npm were installed earlier. If you haven’t already, make sure your npm is up-to-date:

npm install -g npm

Now, let’s install the Supabase CLI globally:

npm install -g supabase

This command downloads and installs the latest stable version of the Supabase CLI. Once it’s done, you can verify the installation by checking its version:

supabase --version

This should output the version number, confirming that the CLI is installed correctly. Next, we need to initialize Supabase in a directory where you want to manage your projects. Let’s create a dedicated directory for our Supabase projects. You can choose any location, but something like ~/supabase-projects is logical.

mkdir ~/supabase-projects
cd ~/supabase-projects

Inside this directory, we’ll initialize a new Supabase project. Even though we’re setting up a local instance, we still use the CLI’s init command. This creates a .supabase directory and a supabase folder containing configuration files. For a local setup, we don’t need to link it to a remote project initially. So, just run:

supabase init

This command creates the necessary files and directories for your local Supabase project. You’ll see a supabase folder appear. Inside this folder, you’ll find files like config.toml and migrations . The config.toml file is where you’ll define your project settings, including database connection details and other configurations. For a local development setup, the defaults are often sufficient to get started. However, when you’re ready to connect to your self-hosted instance, you’ll need to configure this file to point to your local Supabase deployment. For now, we’re just setting up the structure. The migrations folder is where your database schema changes will live. It’s good practice to keep your schema in version-controlled migration files. The init command sets up this structure for you. Remember, this init command is for setting up the client configuration. The actual instance of Supabase will be started using Docker Compose. So, while this step is important for managing your local database schema and configurations, it doesn’t start the Supabase backend services themselves. We’ll get to that in the next section. Keep this directory structure in mind as we proceed; it’s where you’ll be working with your database migrations and project settings going forward.

Setting Up and Running Supabase Locally with Docker Compose

Now for the main event, guys: getting the actual Supabase services running on your Ubuntu 22.04 machine using Docker Compose! This is where all the magic happens. Supabase provides an official Docker Compose file that sets up all the necessary services (Postgres, GoTrue for auth, Kong for API gateway, Realtime, Storage, etc.) in isolated containers. It’s the most straightforward way to get a full Supabase stack running locally.

First, navigate back to the directory where you ran supabase init . If you created ~/supabase-projects , make sure you are in that directory:

cd ~/supabase-projects

Now, we need to download the docker-compose.yml file. Supabase provides a convenient way to do this using their CLI. Run the following command:

supabase start

Wait, what just happened? Actually, the supabase start command does more than just initialize. If it detects you don’t have a docker-compose.yml or .env file, it will attempt to generate them and then start the services. This is the most streamlined approach! If for some reason supabase start doesn’t automatically download the docker-compose.yml or if you prefer to manage it manually, you can use this command instead:

supabase db reset --docker

This command will also prompt you to create a docker-compose.yml if it doesn’t exist and will reset your local database. Let’s assume supabase start worked as expected and downloaded the necessary files. It will create a docker-compose.yml file and potentially a .env file in your current directory ( ~/supabase-projects ). The .env file stores sensitive information like API keys and database passwords. Never commit this file to version control!

Once the docker-compose.yml file is in place, you can start the Supabase services using Docker Compose. Run this command from the same directory:

docker compose up -d

The -d flag stands for detached mode, which means the containers will run in the background. Docker Compose will pull the necessary images (if you don’t have them already) and start all the defined services. This might take a few minutes the first time, as it needs to download all the container images. You’ll see a lot of output as the containers spin up.

To check the status of your running Supabase containers, you can use:

docker compose ps

This command will list all the containers managed by Docker Compose in the current directory and show you their status (e.g., Up , Exited ). You should see containers for db , auth , storage , rest , realtime , and studio . If everything is running correctly, all statuses should be Up .

If you encounter any issues, you can view the logs of the containers using:

docker compose logs

You can also view logs for a specific service, like the database:

docker compose logs db

To stop the Supabase services, simply run:

docker compose down

This command stops and removes the containers, networks, and volumes defined in the docker-compose.yml file. Use docker compose down -v if you want to remove the volumes as well (this will delete your database data!).

Once the services are up, you can access the Supabase Studio (the dashboard) by navigating to http://localhost:54323 in your web browser. You’ll be greeted with the Supabase login screen. The default credentials are often printed in the terminal output after supabase start or can be found in the .env file if it was generated. Typically, the email is test@example.com and the password is password for local development. Remember, these are for local development ONLY and should never be used in production.

Accessing Your Supabase Instance and Dashboard

Alright, you’ve successfully spun up Supabase on your Ubuntu 22.04 server using Docker Compose. High five! Now, let’s talk about how you actually use it. The primary way to interact with your local Supabase instance is through its web-based dashboard, known as Supabase Studio . This is your central hub for managing your database, users, API settings, and more. As mentioned before, after running docker compose up -d , you can access Studio by opening your web browser and going to http://localhost:54323 . You should see a login page.

For a default local setup, Supabase usually provides placeholder credentials. Typically, the email address is test@example.com and the password is password . If these don’t work, check the output of the supabase start command or look for a .env file in your project directory ( ~/supabase-projects ). This .env file contains environment variables for your Supabase services, including credentials. Seriously, guys, make sure you secure this .env file and never push it to GitHub or any public repository.

Once you log in, you’ll be greeted by the Supabase Studio interface. It looks very similar to the cloud-hosted version you might be familiar with. On the left-hand sidebar, you’ll find access to various sections:

• Table Editor: This is where you can visually create, modify, and query your PostgreSQL tables. You can add columns, define data types, set constraints, and even insert data directly. It’s incredibly intuitive for database management.
• SQL Editor: For those who prefer writing raw SQL, this is your playground. You can execute any SQL query directly against your database. This is powerful for complex operations, data manipulation, and schema management.
• Authentication: Here, you can manage your users, configure authentication providers (like email/password, magic links, social logins if you set them up), and set up policies for row-level security.
• Storage: If your application needs file storage, this is the place. You can create buckets, upload files, and set permissions for accessing them.
• Realtime: Supabase’s realtime capabilities allow you to subscribe to database changes. You can configure realtime settings and see active subscriptions here.
• API Settings: This section provides information about your RESTful API endpoints, which are automatically generated based on your database schema. You can also manage API keys and CORS settings.

Beyond the Studio, you’ll interact with your Supabase instance programmatically from your applications. The Supabase CLI is essential for this. You can use it to:

• Generate TypeScript/JavaScript client types: Run supabase gen types typescript --local > src/types/supabase.ts (adjust the path as needed) to generate types based on your local database schema. This provides excellent autocompletion and type safety in your frontend code.
• Manage migrations: As you change your database schema (e.g., adding tables, columns, functions), you should create migration files. Use supabase migration new <migration-name> to create a new migration file, edit it with your SQL, and then apply it using supabase migration up . The CLI automatically handles applying migrations to your local Docker instance.
• Access the database directly: You can use tools like psql to connect to your local Supabase database if needed. The connection details (host, port, user, database name) are usually found in your .env file or can be inferred from the Docker Compose setup. Typically, you can connect using psql postgresql://postgres:your_password@localhost:5432/postgres (replace your_password with the password from your .env file).

Remember, this setup is primarily for development and testing . For production environments, you would typically deploy Supabase to a more robust infrastructure, perhaps using Kubernetes or dedicated servers, and manage its configuration and scaling accordingly. But for getting your feet wet and building out features locally, this Ubuntu 22.04 setup is absolutely fantastic.

Troubleshooting Common Issues

Even with the best guides, sometimes things don’t go exactly as planned, right? It happens to the best of us! Setting up Supabase on Ubuntu 22.04 can occasionally throw a few curveballs. Let’s cover some common issues you might run into and how to tackle them. One of the most frequent problems is services not starting correctly. If docker compose ps shows containers that are Exited or Restarting , the first step is always to check the logs. Use docker compose logs or docker compose logs <service_name> (e.g., docker compose logs db ). The output will often give you a clue about what went wrong – maybe a configuration error, a port conflict, or a dependency issue.

Another common headache is port conflicts . By default, Supabase Studio runs on port 54323 , the API on 54321 , and the database itself might try to use 5432 . If you have other applications running on your Ubuntu machine that are already using these ports, Docker Compose might fail to start the services. You can check which ports are in use with sudo lsof -i -P -n | grep LISTEN . If you find a conflict, you can often remap the ports in the docker-compose.yml file. For example, to change the Studio port from 54323 to 8000 , you would find the studio service definition and change 54323:80 to 8000:80 . Make sure to update the URL you use to access Studio accordingly (e.g., http://localhost:8000 ) . Similarly, you might need to adjust the POSTGRES_PORT environment variable in your .env file if you change the database port.

Authentication issues are also pretty common. If you can’t log in to Studio, or if your application can’t authenticate users, double-check the credentials in your .env file and ensure they match what you’re trying to use. Also, verify that the auth container is running correctly. Sometimes, a simple docker compose down followed by docker compose up -d can resolve transient issues.

Database connection problems are another area where people get stuck. Ensure that your application is using the correct connection string. For a local setup, it typically looks something like postgresql://postgres:YOUR_DB_PASSWORD@localhost:5432/postgres . Make sure YOUR_DB_PASSWORD is replaced with the actual password from your .env file, and that the port ( 5432 ) matches what the db service is configured to use (check docker-compose.yml ). If you’re using the Supabase client libraries (JavaScript, Python, etc.), they usually abstract this, but you’ll need to provide the correct SUPABASE_URL and SUPABASE_ANON_KEY . For your local setup, the SUPABASE_URL is typically http://localhost:54321 (or whatever port your API gateway is running on), and the SUPABASE_ANON_KEY can often be found in the .env file or is a placeholder like eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS10ZXN0Iiwicm9sZSI6ImFub24iLCJleHAiOjE5ODY3OTk2NjF9.ek5fdlV4Z2E0aFhhV0hoUmxsb1hBWWxlZ250c01hM2xwd096ckFnbzlhQQ . Again, check your .env file for the correct keys . If your application can’t reach the API, check the logs for the kong (API Gateway) and rest (PostgREST) services.

Finally, if you need to reset your local Supabase instance completely, including the database, you can use docker compose down -v to stop and remove all containers and volumes, then run docker compose up -d again to start fresh. You might also want to run supabase db reset to ensure your migrations are reapplied correctly. Don’t be afraid to experiment with these commands, guys. The beauty of Docker is that it’s relatively easy to spin up, tear down, and rebuild environments without messing up your host system. Just remember to back up any critical data before performing destructive actions like removing volumes!

Conclusion: Your Supabase Journey Begins!

And there you have it, folks! You’ve successfully navigated the process of setting up Supabase on your Ubuntu 22.04 system. From updating your server and installing Docker to downloading the CLI, configuring services with Docker Compose, and accessing the slick Supabase Studio dashboard, you’re now equipped with your very own self-hosted backend. This is a massive step towards having complete control over your application’s data and infrastructure. Being able to run Supabase locally on Ubuntu 22.04 is incredibly valuable for development, testing, and even for smaller projects where you want to avoid cloud costs or vendor lock-in. You’ve learned how to start, stop, and manage the Supabase services, troubleshoot common hiccups, and interact with your database and APIs. This setup provides a robust PostgreSQL database, authentication services, real-time capabilities, and more, all running right on your machine. It’s a fantastic way to accelerate your development workflow, experiment with new features, and build amazing applications with confidence. Remember the key commands: sudo apt update && sudo apt upgrade , docker compose up -d to start, docker compose ps to check status, docker compose logs for debugging, and docker compose down to stop. Keep that supabase CLI handy for managing migrations and generating types. As you grow, you can explore more advanced deployment options for production, but this local setup is the perfect launchpad. So go ahead, start building, hacking, and creating. Your Supabase journey has officially begun, and the possibilities are endless! Happy coding, everyone!