Flora Server

Backend service for Flora Suite, providing cloud capabilities for Flora Web/Desktop applications.

WARNING: This codebase is unstable and may undergo major changes. Do not use it in production.

Tech Stack

• Runtime: Bun
• Framework: Hono
• Database: PostgreSQL + Drizzle ORM
• Validation: Zod
• Authentication: JWT (Access + Refresh Token)

Quick Start

Prerequisites

• Bun >= 1.1
• Docker (for database)

Installation

# Install dependencies
bun install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

Development

# Start database services (PostgreSQL + Redis)
bun run docker:dev:db

# Push database schema
bun run db:push

# Start development server (with hot-reload)
bun run dev

Server will be available at http://localhost:3000

Install

GitHub Releases are the only source of prebuilt binaries. Published binary assets are hosted in flora-suite/flora-server.

macOS and Linux

Install the latest release with:

curl -fsSL https://raw.githubusercontent.com/flora-suite/flora-server/main/scripts/install.sh | sh

Install a specific release or choose a different directory:

curl -fsSL https://raw.githubusercontent.com/flora-suite/flora-server/main/scripts/install.sh | sh -s -- --version v0.1.0
curl -fsSL https://raw.githubusercontent.com/flora-suite/flora-server/main/scripts/install.sh | INSTALL_DIR=/usr/local/bin sh

The installer detects the CPU architecture and, on Linux, glibc versus musl. It checks the downloaded archive against the release checksums.txt, installs to ~/.local/bin by default, and only tells you how to update PATH; it never edits your shell configuration. To uninstall, remove the installed binary:

rm "${INSTALL_DIR:-$HOME/.local/bin}/flora-server"

Windows

Download the Windows x64 archive from GitHub Releases, verify it with checksums.txt, extract it, and place flora-server.exe on PATH. A Scoop bucket template lives in packaging/scoop/bucket. After synchronizing it to flora-suite/scoop-bucket and replacing its release SHA-256 placeholder:

scoop bucket add flora-suite https://github.com/flora-suite/scoop-bucket
scoop install flora-server

Homebrew (macOS)

packaging/homebrew/Formula/flora-server.rb is a formula template. Sync it to the separate flora-suite/homebrew-tap repository and replace the version and two archive SHA-256 placeholders for each release. Users can then run:

brew install flora-suite/tap/flora-server

Debian and RPM packages

Each release also includes Linux x64 glibc .deb and .rpm assets. Download the matching asset and install it locally, for example:

sudo dpkg -i flora-server-<version>-linux-x64.deb
sudo dnf install ./flora-server-<version>-linux-x64.rpm

These packages install /usr/bin/flora-server; remove them with your distribution's package manager. No online APT or RPM repository is provided yet. Repository metadata may later be published through GitHub Pages in flora-suite/packages to support apt install and dnf install.

Supported binaries

Platform	Architectures	Compatibility
Linux	x64, arm64	glibc; x64 glibc uses Bun's baseline CPU target
Linux	x64, arm64	musl builds for Alpine; x64 uses Bun's baseline CPU target
macOS	x64, arm64	Intel and Apple Silicon
Windows	x64, arm64	x64 uses Bun's baseline CPU target

Every archive contains the executable, documentation, and flora-server.env.example; it does not include source code, Bun, dependencies, or credentials. Copy the template to .env beside the executable and replace its placeholder values before starting the server from that directory, or load those values through your service manager's environment-file mechanism.

Full Docker Development

# Start all services (app + database + redis + minio)
bun run docker:dev

# View logs
bun run docker:dev:logs

# Stop all services
bun run docker:dev:down

API Endpoints

Health Check

GET /api/health

Authentication

Method	Endpoint	Description	Auth
POST	/api/auth/register	Register new user	No
POST	/api/auth/login	User login	No
POST	/api/auth/refresh	Refresh access token	No
POST	/api/auth/logout	Logout (invalidate token)	No
GET	/api/auth/me	Get current user	Yes

Project Structure

flora-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── app.ts            # Hono app configuration
│   ├── config/           # Environment configuration
│   ├── db/               # Database (Drizzle ORM)
│   │   └── schema/       # Table definitions
│   ├── middleware/       # Middlewares (auth, cors, error, logger)
│   ├── repositories/     # Data access layer
│   ├── routes/           # API routes
│   ├── services/         # Business logic
│   ├── types/            # TypeScript types
│   └── utils/            # Utility functions
├── docker/               # Docker configurations
├── drizzle.config.ts     # Drizzle configuration
└── package.json

Scripts

# Development
bun run dev              # Start dev server (hot-reload)
bun run start            # Start production server
bun run build            # Build one standalone executable for the current platform
bun run release:build    # Compile all standalone binaries into dist/bin
bun run release:package  # Build all release archives, checksums, .deb, and .rpm

# Database
bun run db:generate      # Generate migrations
bun run db:migrate       # Run migrations
bun run db:push          # Push schema (dev only)
bun run db:studio        # Open Drizzle Studio

# Code Quality
bun run typecheck        # TypeScript check
bun run lint             # ESLint check
bun run lint:fix         # ESLint fix

# Tests
bun run test             # Unit/integration tests with isolated Bun processes
bun run test:db          # Start an isolated flora_test database, migrate, and run all tests including E2E

# Docker
bun run docker:dev       # Start dev environment
bun run docker:dev:db    # Start database only
bun run docker:dev:down  # Stop dev environment
bun run docker:build     # Build production image
bun run docker:prod      # Start production environment

Environment Variables

Variable	Required	Default	Description
PORT	No	3000	Server port
NODE_ENV	No	development	Environment
DATABASE_URL	Yes	-	PostgreSQL connection URL
JWT_SECRET	Yes	-	JWT signing secret (min 32 chars)
JWT_ACCESS_EXPIRES_IN	No	15m	Access token expiry
JWT_REFRESH_EXPIRES_IN	No	7d	Refresh token expiry
CORS_ORIGINS	No	http://localhost:8080	Allowed origins (comma-separated)
LOG_LEVEL	No	info	Log level (debug/info/warn/error)

Docker Services

Development (docker/docker-compose.yml)

Service	Port	Description
app	3000	Flora Server (hot-reload)
postgres	5432	PostgreSQL database
redis	6379	Redis cache
minio	9000/9001	S3-compatible storage
drizzle-studio	4983	Database GUI (optional)

Production image

The production Docker image compiles the Alpine-compatible standalone binary during its build and copies only /usr/local/bin/flora-server into the final image. The final image contains neither Bun, node_modules, nor application source code.

License

MIT