Getting Started

Quick Start

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/jueewo/appkask.git
cd appkask

# Start everything
docker compose up -d

# Open in browser
open http://localhost:3000

The first run will:

• Create the SQLite database (media.db)
• Apply all migrations automatically
• Create the storage directory structure
• Start the web server on port 3000

Option 2: Build from Source

# Prerequisites: Rust toolchain, FFmpeg, Ghostscript, cwebp
cargo build --release

# Configure
cp .env.example .env
# Edit .env with your settings

# Run
./target/release/video-server

First Steps After Login

1. Enable emergency login (development): Set ENABLE_EMERGENCY_LOGIN=true in .env
2. Create a workspace: Click “New Workspace” and give it a name
3. Create a folder: Navigate into your workspace, create a folder
4. Assign a type: Click the folder settings icon, choose “media-server”
5. Upload media: The folder now shows an upload interface — drag and drop your files
6. Share: Click “Share” to generate an access code — send the link to anyone

Environment Variables

# Required
DATABASE_URL=sqlite:media.db
STORAGE_DIR=./storage

# Authentication (OIDC)
OIDC_ISSUER=https://auth.example.com
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_secret
OIDC_REDIRECT_URI=http://localhost:3000/auth/callback

# Development
ENABLE_EMERGENCY_LOGIN=true

# Production
RUN_MODE=production

Architecture

The Stack

Workspace Crate Architecture

AppKask is a Cargo workspace with 34 crates organized by domain:

crates/
  common/              # Shared types, storage, database
  media-core/          # Media detection, EXIF extraction
  media-manager/       # Upload, serve, search, CRUD
  video-manager/       # HLS transcoding (8-stage pipeline)
  access-control/      # 4-layer permission model
  access-codes/        # Shareable access links
  access-groups/       # Team roles and invitations
  user-auth/           # OIDC + session management
  workspace-manager/   # Workspace browser and folder types
  vault-manager/       # Storage vault isolation
  site-generator/      # Astro site generation
  course/              # Course viewer + presentations
  ...and 22 more

The Dual-Use Pattern

Every app crate implements the FolderTypeRenderer trait for embedded mode (inside workspace browser) and exports a Router for standalone mode (own URL). Same logic, same templates, two deployment modes.

Storage Layout

storage/
  workspaces/{workspace_id}/     # File browser content
    folder-a/                    # Regular folder
    media-gallery/               # Typed folder (media-server)
  vaults/{vault_id}/             # Media pipeline storage
    media/
      images/{slug}.webp
      videos/{slug}/index.m3u8
      documents/{filename}
    thumbnails/
      images/{slug}_thumb.webp
      videos/{slug}_thumb.webp

Rate Limiting

Three tiers based on resource intensity: