orochibraru/penombre repository overview

⁠Penombre

A modern, self-hosted cloud storage solution with mobile and web clients

Penombre is a comprehensive file storage and synchronization platform that provides you with complete control over your data. Built with modern technologies and designed for both individual users and organizations who want the convenience of cloud storage without sacrificing privacy and control.

⁠Getting Started

1. Get the .env file curl -o .env https://raw.githubusercontent.com/orochibraru/penombre/refs/heads/main/.example.env

2. Edit the .env file with your configuration (see below for details)

3. Start the application with Docker Compose:

services:
    app:
        image: orochibraru/penombre:latest
        depends_on:
            db:
                condition: service_healthy
        ports:
            - 3000:3000
        restart: unless-stopped
        volumes:
            - storage_data:/data
        env_file: .env
        environment:
            - DATABASE_URL=postgresql://postgres:postgres@db:5432/penombre

    db:
        image: postgres:17-alpine
        restart: unless-stopped
        ports:
            - 5432:5432
        environment:
            - POSTGRES_USER=${POSTGRES_USER-postgres}
            - POSTGRES_PASSWORD=${POSTGRES_PASSWORD-postgres}
            - POSTGRES_DB=${POSTGRES_DB-penombre}
        volumes:
            - postgres_data:/var/lib/postgresql/data
        healthcheck:
            test:
                [
                    CMD-SHELL,
                    "sh -c 'pg_isready -U ${POSTGRES_USER-postgres} -d ${POSTGRES_DB-penombre}'",
                ]
            interval: 1s
            timeout: 2s
            retries: 10
            start_period: 3s

volumes:
    postgres_data:
        driver: local
    storage_data:
        driver: local

⁠Features

• Web Interface: Modern, responsive web application built with SvelteKit
• Mobile App: Native mobile experience with Expo/React Native
• Authentication: Secure authentication via Better Auth with OAuth providers
• File Management: Upload, download, organize files and folders
• Smart Categories: Automatic categorization of files (images, documents, music, etc.)
• Soft Trash: Recoverable file deletion with trash support
• Self-Hosted: Complete control over your data and infrastructure
• Docker Support: Easy deployment with Docker Compose
• Recent Files: Quick access to recently modified files

⁠Environment Variables

See .example.env⁠ for a complete reference.

⁠Core

⁠Database

⁠Authentication

⁠OAuth Providers (Optional)

Configure OAuth providers using the pattern OAUTH_<PROVIDER>_<SETTING>:

⁠SMTP (Optional)

⁠Architecture

Penombre is a monorepo with the following packages:

packages/
├── web/     # SvelteKit app (frontend + Hono API backend)
└── mobile/  # Expo/React Native mobile app

⁠Database

⁠Web Package (packages/web)

The web package is a full-stack SvelteKit application:

• Frontend: SvelteKit with Svelte 5, TailwindCSS, and shadcn-svelte components
• Backend API: Hono routers integrated into SvelteKit server routes
• Database: PostgreSQL with Drizzle ORM (user accounts, activity logging)
• Storage: Local filesystem storage under STORAGE_PATH (default /data)
• Auth: Better Auth for authentication

⁠Mobile Package (packages/mobile)

• Framework: Expo with React Native
• Styling: NativeWind (TailwindCSS for React Native)
• Routing: Expo Router (file-based routing)

⁠Development

⁠Prerequisites

• Bun 1.3+ (primary runtime)
• Docker and Docker Compose (for PostgreSQL)
• Node.js (for Expo/mobile development)

⁠Setup

1. Clone the repository

   git clone https://github.com/orochibraru/penombre.git
   cd penombre
   

   Copy

2. Install dependencies

   bun install
   

   Copy

3. Start development services

   bun run dev
   

   Copy

   This starts PostgreSQL via Docker Compose and the Vite dev server for the web app.

4. Access the application

   • Web UI: http://localhost:5173⁠ (Vite default)

⁠Mobile Development

cd packages/mobile
bun install
bunx expo start

⁠Docker Deployment

Build and run the production container:

docker compose up --build

The app will be available at http://localhost:3000⁠.

⁠Backup & Restore

Penombre includes backup and restore scripts to protect your data. Backups include both the PostgreSQL database and all file storage.

⁠Creating a Backup

# With the stack running:
bun run backup

# Or specify a custom backup directory:
./scripts/backup.sh /path/to/backups

This creates a timestamped archive containing:

• database.dump - PostgreSQL custom format dump
• storage.tar.gz - All uploaded files and metadata
• backup.json - Backup metadata

⁠Restoring from Backup

# With the stack running:
bun run restore ./backups/penombre_backup_20240115_120000.tar.gz

# Or directly:
./scripts/restore.sh ./backups/penombre_backup_20240115_120000.tar.gz

⁠Automated Backups

For automated backups, add a cron job:

# Daily backup at 2 AM
0 2 * * * cd /path/to/penombre && ./scripts/backup.sh /path/to/backups >> /var/log/penombre-backup.log 2>&1

⁠Backup Storage Recommendations

• Store backups on a different drive or remote storage
• Keep multiple backup generations (e.g., last 7 days)
• Test restores periodically to verify backup integrity

⁠Development

⁠Tech Stack

• Runtime: Bun
• Web Framework: SvelteKit + Hono
• Frontend: Svelte 5, TailwindCSS 4, shadcn-svelte
• Mobile: Expo, React Native, NativeWind
• Database: PostgreSQL, Drizzle ORM
• Auth: Better Auth
• Linting: Biome

⁠Available Commands

# Root commands
bun run dev          # Start dev servers (DB + web)
bun run test         # Run tests
bun run build        # Build all packages
bun run lint         # Lint with Biome
bun run lint:fix     # Lint and fix issues
bun run check        # Type-check all packages

# Web package (packages/web)
bun run dev          # Start Vite dev server
bun run build        # Build for production
bun run check        # Type-check with svelte-check
bun run db:generate  # Generate Drizzle migrations

# Mobile package (packages/mobile)
bunx expo start       # Start Expo dev server
bunx expo run:android # Run on Android
bunx expo run:ios     # Run on iOS

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Acknowledgments

Built with these open-source technologies:

• SvelteKit⁠ - Full-stack web framework
• Hono⁠ - Lightweight web framework for API routes
• shadcn-svelte⁠ - UI components
• Bun⁠ - JavaScript runtime and toolkit
• Expo⁠ - React Native framework
• Drizzle ORM⁠ - TypeScript ORM
• Better Auth⁠ - Authentication library
• PostgreSQL⁠ - Database
• Biome⁠ - Linter and formatter