Installation

This guide walks you through installing Fluxbase on your system.

Prerequisites

Before installing Fluxbase, ensure you have:

PostgreSQL 14+ - Fluxbase requires PostgreSQL as its database
64-bit Operating System - Linux
1GB RAM minimum (2GB+ recommended for production)
100MB disk space (plus space for your data)

Installing PostgreSQL

Ubuntu/Debian

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

macOS (Homebrew)

brew install postgresql@16
brew services start postgresql@16

Docker

docker run -d \
  --name fluxbase-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=fluxbase \
  -p 5432:5432 \
  postgis/postgis:18-3.6

Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database and user
CREATE DATABASE fluxbase;
CREATE USER fluxbase WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE fluxbase TO fluxbase;
\q

Installing Fluxbase

Choose one of the following installation methods:

Method 1: Download Pre-built Binary (Recommended)

Download the latest release for your platform (~40MB binary):

Linux (x86_64)

curl -L https://github.com/fluxbase-eu/fluxbase/releases/latest/download/fluxbase-linux-amd64 -o fluxbase
chmod +x fluxbase
sudo mv fluxbase /usr/local/bin/

macOS (Intel)

curl -L https://github.com/fluxbase-eu/fluxbase/releases/latest/download/fluxbase-darwin-amd64 -o fluxbase
chmod +x fluxbase
sudo mv fluxbase /usr/local/bin/

Method 2: Docker

Pull and run the official Docker image (~80MB container):

docker pull ghcr.io/fluxbase-eu/fluxbase:latest

docker run -d \
  --name fluxbase \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://fluxbase:password@host.docker.internal:5432/fluxbase \
  -e JWT_SECRET=your-secret-key-change-this \
  ghcr.io/fluxbase-eu/fluxbase:latest

Method 3: Docker Compose

services:
  postgres:
    image: postgis/postgis:18-3.6
    environment:
      POSTGRES_DB: fluxbase
      POSTGRES_USER: fluxbase
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

  fluxbase:
    image: ghcr.io/fluxbase-eu/fluxbase:latest
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgres://fluxbase:postgres@postgres:5432/fluxbase?sslmode=disable
      JWT_SECRET: change-this-to-a-secure-random-string
    ports:
      - "8080:8080"

Start: docker-compose up -d

Method 4: Build from Source

git clone https://github.com/fluxbase-eu/fluxbase.git
cd fluxbase
make build

Configuration

Environment variables:

export DATABASE_URL=postgres://fluxbase:password@localhost:5432/fluxbase
export JWT_SECRET=your-secret-key
export PORT=8080

Or create fluxbase.yaml:

database:
  url: postgres://fluxbase:password@localhost:5432/fluxbase
jwt:
  secret: your-secret-key
storage:
  provider: local
  local_path: ./storage

Initialize Database

Run database migrations:

fluxbase migrate

This will:

Create the auth schema with user tables
Create the storage schema for file metadata
Set up realtime triggers
Initialize system functions

Start Fluxbase

fluxbase

You should see:

🚀 Fluxbase starting...
✅ Database connected: PostgreSQL 16.0
✅ Migrations applied: 4 migrations
✅ Admin UI available at: http://localhost:8080/admin
✅ REST API available at: http://localhost:8080/api/v1
✅ Realtime WebSocket at: ws://localhost:8080/realtime
🎉 Fluxbase is ready! Listening on http://localhost:8080

Verify Installation

1. Check Health

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "version": "0.1.0"
}

2. Access Admin UI

Open http://localhost:8080/admin in your browser.

3. Create First User

curl -X POST http://localhost:8080/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "SecurePassword123"
  }'

4. Test REST API

Create a table:

-- Connect to your database
psql postgres://fluxbase:password@localhost:5432/fluxbase

-- Create a test table
CREATE TABLE tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  completed BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Query via REST API:

curl http://localhost:8080/api/v1/tables/tasks

Troubleshooting

Issue	Solution
Database connection failed	Check PostgreSQL running: `systemctl status postgresql`, verify `DATABASE_URL`, ensure database exists
Port already in use	Change port: `PORT=8081 fluxbase` or kill process: `lsof -ti:8080 \| xargs kill`
Migrations failed	Check PostgreSQL logs, ensure user has permissions, drop/recreate DB (dev only)
Permission denied	Grant permissions: `GRANT ALL ON SCHEMA public TO fluxbase;`

Upgrading

Binary:

pg_dump fluxbase > backup.sql  # Backup first!
curl -L https://github.com/fluxbase-eu/fluxbase/releases/latest/download/fluxbase-linux-amd64 -o fluxbase
chmod +x fluxbase && ./fluxbase migrate && ./fluxbase

Docker:

docker pull ghcr.io/fluxbase-eu/fluxbase:latest && docker-compose up -d

Running as systemd Service

Create /etc/systemd/system/fluxbase.service:

[Unit]
Description=Fluxbase
After=postgresql.service

[Service]
Type=simple
Environment="DATABASE_URL=postgres://fluxbase:password@localhost:5432/fluxbase"
Environment="JWT_SECRET=your-secret-key"
ExecStart=/usr/local/bin/fluxbase
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable: systemctl enable fluxbase && systemctl start fluxbase