From c0f3523a9cb0650f2c26230e9ed50b7f01722301 Mon Sep 17 00:00:00 2001 From: ergosteur <1992147+ergosteur@users.noreply.github.com> Date: Sat, 7 Mar 2026 02:50:18 -0500 Subject: [PATCH] docs: update README and GEMINI with Docker usage and new features --- GEMINI.md | 40 ++++++++++++------------ README.md | 89 ++++++++++++++++++++++++++++++++++------------------- compose.yml | 12 ++++++++ 3 files changed, 91 insertions(+), 50 deletions(-) create mode 100644 compose.yml diff --git a/GEMINI.md b/GEMINI.md index b667414..0b97fc8 100644 --- 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. diff --git a/README.md b/README.md index edb6081..bedcf2f 100644 --- 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`) diff --git a/compose.yml b/compose.yml new file mode 100644 index 0000000..ec3ddab --- /dev/null +++ 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