docs: update README and GEMINI with Docker usage and new features

2026-07-04 11:07:15 -04:00 · 2026-03-07 02:50:18 -05:00
parent 6f5021638c
commit c0f3523a9c
3 changed files with 91 additions and 50 deletions
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -2,38 +2,40 @@

 ## Project Overview

-**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It allows users to load local archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories.
+**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It supports both local directory loading and self-hosted server modes.

 ### Key Technical Features
- **Local Archive Loading:** Uses the `webkitdirectory` API to scan and process local files securely on the client-side.
+- **Persistent Caching:** Uses `idb-keyval` (IndexedDB) to cache parsed metadata and server-side media URLs. Subsequent loads of the same archive are instant.
+- **Glassy Scanner UI:** A custom-built glassmorphism scanning dashboard with throttled (1s) dynamic blurred backgrounds and a high-density system log.
 - **Support for Multiple Formats:** Recognizes official Instagram export structures and Instaloader regex-based naming conventions.
- **Compressed Metadata**: Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered).
- **Dynamic Media Grid**: Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment.
- **Story Viewer**: Native-like story experience with segmented progress bars, automated playback, audio controls, and chronological sorting.
- **Auto-Unmute**: Videos default to unmuted when opened in full view for a better user experience.
- **PWA Ready**: Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience.
+- **Compressed Metadata:** Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered).
+- **Navigation Protection:** Intercepts browser history (`popstate`) and exit events (`beforeunload`) to prevent session loss while maintaining a "Back to Explorer" SPA flow.
+- **Production-Ready Docker:** Multi-stage Docker builds using `node:slim` to serve both the Express API and the Vite-built frontend.

 ### Main Technologies
 - **Frontend:** React 19, Vite, TypeScript
 - **Styling:** Tailwind CSS (v4)
 - **Icons:** Lucide React
 - **Animations:** Framer Motion (`motion/react`)
- **Utility:** Date-fns, clsx, tailwind-merge
- **Decompression**: xz-decompress (WASM)
+- **Persistence:** IndexedDB (`idb-keyval`)
+- **Backend:** Express, tsx (for server-side scanning)
+- **Decompression:** xz-decompress (WASM)

 ## Commands
 - `npm install`: Install project dependencies.
 - `npm run dev`: Start the local development server on port 3000.
 - `npm run build`: Generate the production-ready build in the `dist` folder.
- `npm run preview`: Locally preview the production build.
- `npm run lint`: Execute TypeScript type-checking (`tsc --noEmit`).
+- `npm run server`: Start the backend server to scan `./_sample-archives`.
+- `npm run lint`: Execute TypeScript type-checking.
+
+## Production Deployment
+The project is containerized and available on GHCR. It expects a volume mount at `/archives` containing subdirectories for each user.
+
+### Key Environment Variables
+- `PORT`: Server port (default: 3000)
+- `ARCHIVES_DIR`: Path to the archives collection (default: /archives)

 ## Development Conventions
- **Component Architecture:** Functional components with modern hooks.
- **State Management**: React `useState`, `useMemo`, and `useCallback` for optimized performance during large archive scans.
- **File Handling:** Privacy-focused client-side scanning of archive directories.
- **Project Structure:**
-  - `src/App.tsx`: Main entry point containing application logic and UI components.
-  - `src/main.tsx`: React DOM mounting.
-  - `src/index.css`: Global styles and Tailwind imports.
-  - `vite.config.ts`: Project build and PWA configuration.
+- **Username Logic:** The directory name is the definitive source of truth for the account username.
+- **State Management:** React `useState`, `useMemo`, and `useCallback` for optimized performance.
+- **File Handling:** Uses `RemoteArchiveFile` and `LocalArchiveFile` classes to provide a unified `ArchiveFile` interface for the parser.
--- a/README.md
+++ b/README.md
@@ -4,40 +4,67 @@ A high-performance React PWA for browsing archived Instagram data with a native-

 ## Features

- **Local Privacy**: All processing is done client-side using browser APIs. Your data never leaves your computer.
+- **Persistent Caching**: Uses IndexedDB to store parsed archives locally. Subsequent loads are near-instant.
+- **Glassy Scanning UI**: A modern, translucent white terminal experience with a dynamic blurred background of your media.
+- **Local Privacy**: All processing is done client-side. Even when using the self-hosted version, your media is processed locally in your browser.
 - **Multiple Formats**: Supports official Instagram JSON exports and Instaloader regex-based naming conventions.
- **Metadata Support**: Robust parsing of `.json` and `.json.xz` files for captions, timestamps, and story metadata.
 - **Story Viewer**: Native-like story experience with segmented progress bars, auto-playback, and audio controls.
- **Media Grid**: Customizable 1:1 or 3:4 grid views with adjustable offsets for aesthetic alignment.
- **Auto-Deduplication**: Intelligently prefers video files over thumbnail images for the same post.
+- **Customizable Grid**: 1:1 or 3:4 aspect ratios with adjustable "bumps" for aesthetic alignment.
+- **Navigation Protection**: Intercepts accidental browser "Back" or "Refresh" actions to protect your current session.

-## Run Locally
+## Deployment
+
+### Docker (Recommended)
+
+The easiest way to run InstaArchive is using Docker.
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -v /path/to/your/archives:/archives:ro \
+  ghcr.io/ergosteur/instaarchive-viewer:latest
+```
+
+### Docker Compose
+
+Create a `compose.yml` file:
+
+```yaml
+services:
+  instaarchive:
+    image: ghcr.io/ergosteur/instaarchive-viewer:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./archives:/archives:ro
+```
+
+Run with:
+```bash
+docker compose up -d
+```
+
+## Supported Archive Structure
+
+Place your archive folders inside the mounted `/archives` directory. The directory name will be used as the account username.
+
+### Example Structure:
+```text
+archives/
+├── wanderlust_explorer/          # Instaloader format
+│   ├── 2024-01-01_12-00-00_UTC.jpg
+│   ├── 2024-01-01_12-00-00_UTC.json.xz
+│   └── wanderlust_explorer_profile_pic.jpg
+└── pixel_architect/             # Instagram Export format
+    ├── 2023-12-25_pixel_architect - post_123.jpg
+    ├── 2023-12-25_pixel_architect - post_123.json
+    └── pixel_architect.jpg
+```
+
+## Local Development

 **Prerequisites:** Node.js (LTS recommended)

-1. **Install dependencies:**
-   ```bash
-   npm install
-   ```
-
-2. **Start the development server:**
-   ```bash
-   npm run dev
-   ```
-
-3. **Open in browser:**
-   Navigate to `http://localhost:3000` and select your Instagram archive directory.
-
-## Building for Production
-
-To generate a production-ready build in the `dist` folder:
-
-```bash
-npm run build
-```
-
-To preview the build:
-
-```bash
-npm run preview
-```
+1. **Install dependencies:** `npm install`
+2. **Start dev server:** `npm run dev`
+3. **Start local backend:** `npm run server` (Optional, serves `./_sample-archives`)
--- a/compose.yml
+++ b/compose.yml
@@ -0,0 +1,12 @@
+services:
+  instaarchive:
+    image: ghcr.io/${GITHUB_REPOSITORY:-ergosteur/instaarchive-viewer}:latest
+    build: .
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./archives:/archives:ro
+    environment:
+      - PORT=3000
+      - ARCHIVES_DIR=/archives
+    restart: unless-stopped