Self-Hosting a Lightweight Firebase Auth Alternative: Deploying SuperTokens on Docker Rootless

Introduction: The Shift Toward Sovereignty in Authentication

In the modern landscape of web development, Firebase Authentication has long been the default choice for developers seeking rapid deployment. However, as projects scale, the limitations of proprietary, closed-source ecosystems become apparent. Issues such as vendor lock-in, rising costs, and data residency concerns are driving a significant shift toward self-hosted solutions. Enter SuperTokens: an open-source, flexible, and developer-centric authentication framework that provides the perfect middle ground between building from scratch and relying on a black-box SaaS provider.

This article provides an in-depth technical walkthrough on self-hosting SuperTokens. To elevate the security posture of your infrastructure, we will focus on deploying this solution using Docker Rootless mode—a method that significantly reduces the attack surface of your host machine by running containers without administrative privileges.

Why Choose SuperTokens Over Firebase Auth?

While Firebase is convenient, SuperTokens offers several strategic advantages for businesses and privacy-conscious developers:

Data Ownership: Your user data remains in your database (PostgreSQL or MySQL), not on a third-party server.
Customizability: Unlike the rigid structures of Firebase, SuperTokens allows for deep customization of the authentication flow, from session management logic to UI components.
Cost Efficiency: Firebase’s pricing can become unpredictable as your user base grows. Self-hosting with SuperTokens allows for linear, predictable infrastructure costs.
Security Architecture: SuperTokens employs a unique rotating refresh token strategy that mitigates many common session hijacking risks.

Understanding the Docker Rootless Advantage

Standard Docker installations run with root privileges. If a container is compromised, the attacker could potentially gain control over the entire host system. Docker Rootless allows the Docker daemon and containers to run as an unprivileged user. By deploying SuperTokens in this environment, you ensure that even in the unlikely event of a service vulnerability, your underlying server infrastructure remains isolated and protected.

Prerequisites for Installation

Before proceeding, ensure your environment meets the following requirements:

A Linux server (Ubuntu 22.04 LTS or newer recommended).
Docker installed and configured in Rootless Mode.
A registered domain name for SSL termination.
Basic familiarity with Docker Compose and SQL databases.

Phase 1: Setting Up the Infrastructure

The core of a SuperTokens deployment consists of two main components: the SuperTokens Core (the microservice handling the logic) and a Database (PostgreSQL is highly recommended for its robustness).

Configuring the Environment

First, create a dedicated directory for your deployment to maintain organization and security:

mkdir ~/supertokens-deploy && cd ~/supertokens-deploy

Within this directory, create a docker-compose.yml file. Running this in Rootless mode requires no special changes to the file itself, but you must ensure your user has the correct permissions to bind ports above 1024, or use a reverse proxy like Nginx to handle external traffic on ports 80 and 443.

Phase 2: Defining the Docker Compose Architecture

Below is a production-ready configuration for SuperTokens and PostgreSQL. This setup ensures that your authentication core is decoupled from the data layer.

version: '3.8'
services:
  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql
    ports:
      - "3567:3567"
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens_user:secure_password@db:5432/supertokens"
    depends_on:
      - db
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: supertokens_user
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: supertokens
    volumes:
      - ./data:/var/lib/postgresql/data

Securing the Core

In a production environment, you must add an API Key to protect the SuperTokens Core from unauthorized access. This is done by adding the API_KEYS environment variable to the supertokens service in your compose file. Always use a high-entropy string for your keys.

Phase 3: Integration and Frontend Implementation

Once the core is running (verify with curl http://localhost:3567/hello), the next step is integrating the SuperTokens SDK into your application. SuperTokens provides SDKs for all major frameworks, including React, Next.js, and Vanilla JavaScript.

Implementing the Frontend SDK

The frontend SDK handles the complex tasks of cookie management and token refreshing automatically. This is a significant advantage over manual JWT implementations which are often prone to security flaws like XSS-vulnerable storage.

Initialization: Configure the SDK with your apiDomain (the SuperTokens core) and websiteDomain (your app).
Pre-built UI: SuperTokens offers a "Pre-built UI" recipe that saves weeks of development time by providing professionally designed login/signup flows.
Customization: You can override any part of the UI or logic using the Recipe Interface.

Phase 4: Maintenance and Best Practices

Self-hosting requires a proactive approach to maintenance. To ensure your authentication system remains "super," follow these best practices:

1. Regular Backups

Since you own the data, you are responsible for it. Set up a cron job to perform pg_dump on your PostgreSQL container daily. Store these backups in a separate, encrypted off-site location.

2. Monitoring and Logging

Use Docker logs to monitor the health of your SuperTokens Core. In Rootless mode, logs are stored within the user's home directory. Integrating a tool like Prometheus or Grafana can help visualize traffic spikes or failed login attempts.

3. Updates

SuperTokens frequently releases security patches and new features. Update your images by pulling the latest tags and restarting your containers. Because SuperTokens handles database migrations automatically, the process is usually seamless.

Conclusion: The Future of Your Identity Stack

Transitioning from Firebase Auth to a self-hosted SuperTokens setup on Docker Rootless is more than just a technical change; it is a move toward technological independence. By following this guide, you have built an authentication system that is lightweight, highly secure, and entirely under your control.

As your application grows, you can sleep soundly knowing that your user credentials are protected by the isolation of Rootless Docker and the sophisticated session management of SuperTokens. The initial setup effort pays dividends in long-term flexibility, security, and cost savings.