Ephemeral

Ephemeral is a lightweight self-hosted web app for quickly sharing text messages and files across devices.

Chat page

History page

Table of Contents

• Ephemeral
• Features
• Tech Stack
• Requirements (Development Only)
• Configuration
• Docker Deployment
• Development
  • Build and Run Locally
  • Format and Lint

Features:

• Chat-style feed
• Image and video media viewer with thumbnail preview and browser-friendly video playback copies
• Public file links with optional expiry
• Generic file view/download
• Code and text file viewer with syntax highlighting
• Multi-select mode: select multiple items to perform bulk deletion or download all in a single ZIP file
• Upload progress queue for file uploads
• History search: type and date filters, filename, text file body search
• Pagination and infinite scrolling
• Mobile-friendly JSON API
• SQLite data persistence
• Docker deployment
• Hot-reload development

Tech Stack

• Go
• SQLite
• Alpine.js
• HTMX
• HLS.js
• FFmpeg
• Docker & Docker Compose

Requirements (Development Only)

go >= 1.21
node >= 20
npm
ffmpeg
air

Configuration

Environment variables:

PORT=8080
DATA_DIR=./data
SESSION_TTL=30d
COOKIE_SECURE=false
TRUSTED_PROXIES=
CHAT_PAGE_SIZE=100
HISTORY_PAGE_SIZE=100
SEARCH_RESULT_LIMIT=30
MAX_UPLOAD_SIZE=2GiB
TEXT_PREVIEW_MAX=10MiB
BODY_INDEX_MAX=20MiB
MEDIA_WORKER_COUNT=1
MEDIA_PROCESS_TIMEOUT=30m
HLS_MIN_SIZE=100MiB
HLS_MIN_DURATION=5m
UPLOAD_CONCURRENCY=1

Size values accept bytes or KB, MB, GB, TB, KiB, MiB, GiB, TiB. Video uploads are processed asynchronously with FFmpeg. The original file is kept for download, a faststart MP4 playback copy is generated for browser playback, and HLS is generated when either HLS_MIN_SIZE or HLS_MIN_DURATION is reached. The browser UI uses native HLS when available, HLS.js when MediaSource is available, and MP4 fallback otherwise. Set both HLS thresholds to 0 to generate HLS for every video. UPLOAD_CONCURRENCY is capped at 10. Set COOKIE_SECURE=true when serving only over HTTPS. Set TRUSTED_PROXIES to comma-separated proxy IPs/CIDRs only when a trusted reverse proxy sets forwarding headers.

Create local env file:

cp .env.example .env

Docker Deployment

Run with Docker Compose:

docker compose up -d --build

Development

Install web dependencies:

make install-web

Run with hot reload:

make dev

Go to:

http://localhost:8080

Build and Run Locally

Build:

make build

Run:

make run

Clean binary:

make clean

Delete local app data:

make clean-data

Format and Lint

Format:

make format

Lint:

make lint

Auto-fix:

make fix