fix: improve Docker archive discovery and switch to compiled server

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+.git
+.github
+_sample-archives
+Dockerfile
+.dockerignore
+README.md
+GEMINI.md
+metadata.json

.github/workflows/docker-publish.yml

@@ -0,0 +1,47 @@
+name: Docker Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

Dockerfile

@@ -0,0 +1,38 @@
+# Stage 1: Build
+FROM node:20-slim AS build
+
+WORKDIR /app
+
+# Install build dependencies
+COPY package*.json ./
+RUN npm ci
+
+# Copy source and build (frontend and server)
+COPY . .
+RUN npm run build
+
+# Stage 2: Runtime
+FROM node:20-slim AS runtime
+
+# Set production environment
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV ARCHIVES_DIR=/archives
+
+WORKDIR /app
+
+# Install runtime dependencies only
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Copy built assets and server
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/dist-server/server.js ./server.js
+
+# Ensure archives directory exists
+RUN mkdir -p /archives
+
+EXPOSE 3000
+
+# Start server
+CMD ["node", "server.js"]

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).
+- **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.
+- **Navigation Protection:** Intercepts browser history (`popstate`) and exit events (`beforeunload`) to prevent session loss while maintaining a "Back to Explorer" SPA flow.
-- **Story Viewer**: Native-like story experience with segmented progress bars, automated playback, audio controls, and chronological sorting.
+- **Production-Ready Docker:** Multi-stage Docker builds using `node:slim` to serve both the Express API and the Vite-built frontend.
-- **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.
 
 ### 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
+- **Persistence:** IndexedDB (`idb-keyval`)
-- **Decompression**: xz-decompress (WASM)
+- **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 server`: Start the backend server to scan `./_sample-archives`.
-- `npm run lint`: Execute TypeScript type-checking (`tsc --noEmit`).
+- `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.
+- **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 during large archive scans.
+- **State Management:** React `useState`, `useMemo`, and `useCallback` for optimized performance.
-- **File Handling:** Privacy-focused client-side scanning of archive directories.
+- **File Handling:** Uses `RemoteArchiveFile` and `LocalArchiveFile` classes to provide a unified `ArchiveFile` interface for the parser.
-- **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.

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.
+- **Customizable Grid**: 1:1 or 3:4 aspect ratios with adjustable "bumps" for aesthetic alignment.
-- **Auto-Deduplication**: Intelligently prefers video files over thumbnail images for the same post.
+- **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:**
+1. **Install dependencies:** `npm install`
-   ```bash
+2. **Start dev server:** `npm run dev`
-   npm install
+3. **Start local backend:** `npm run server` (Optional, serves `./_sample-archives`)
-   ```
-
-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
-```

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

package-lock.json

@@ -16,6 +16,7 @@
         "date-fns": "^4.1.0",
         "dotenv": "^17.2.3",
         "express": "^4.21.2",
+        "idb-keyval": "^6.2.2",
         "lucide-react": "^0.546.0",
         "motion": "^12.23.24",
         "react": "^19.0.0",
@@ -4954,6 +4955,12 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/idb-keyval": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/idb-keyval/-/idb-keyval-6.2.2.tgz",
+      "integrity": "sha512-yjD9nARJ/jb1g+CvD0tlhUHOrJ9Sy0P8T9MF3YaLlHnSRpwPfpTX0XIvpmw3gAJUmEu3FiICLBDPXVwyEvrleg==",
+      "license": "Apache-2.0"
+    },
     "node_modules/ieee754": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",

package.json

@@ -1,12 +1,14 @@
 {
   "name": "react-example",
   "private": true,
-  "version": "0.0.0",
+  "version": "1.1.1",
   "type": "module",
   "scripts": {
     "dev": "vite --port=3000 --host=0.0.0.0",
-    "build": "vite build",
+    "build": "vite build && npm run build:server",
+    "build:server": "tsc server.ts --esModuleInterop --module ESNext --target ES2022 --moduleResolution bundler --outDir dist-server",
     "preview": "vite preview",
+    "server": "tsx server.ts",
     "clean": "rm -rf dist",
     "lint": "tsc --noEmit"
   },
@@ -19,11 +21,13 @@
     "date-fns": "^4.1.0",
     "dotenv": "^17.2.3",
     "express": "^4.21.2",
+    "idb-keyval": "^6.2.2",
     "lucide-react": "^0.546.0",
     "motion": "^12.23.24",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwind-merge": "^3.5.0",
+    "tsx": "^4.21.0",
     "vite": "^6.2.0",
     "xz-decompress": "^0.2.3"
   },
@@ -32,7 +36,6 @@
     "@types/node": "^22.14.0",
     "autoprefixer": "^10.4.21",
     "tailwindcss": "^4.1.14",
-    "tsx": "^4.21.0",
     "typescript": "~5.8.2",
     "vite": "^6.2.0",
     "vite-plugin-pwa": "^1.2.0"

server.ts

@@ -0,0 +1,123 @@
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+const PORT = process.env.PORT || 3001;
+const ARCHIVES_DIR = path.resolve(process.env.ARCHIVES_DIR || path.join(__dirname, '_sample-archives'));
+
+console.log(`[Server] Initializing...`);
+console.log(`[Server] Environment ARCHIVES_DIR: ${process.env.ARCHIVES_DIR}`);
+console.log(`[Server] Resolved ARCHIVES_DIR: ${ARCHIVES_DIR}`);
+
+// Ensure archives directory exists
+if (!fs.existsSync(ARCHIVES_DIR)) {
+  console.warn(`[Server] Warning: Archives directory not found at ${ARCHIVES_DIR}. Creating it...`);
+  fs.mkdirSync(ARCHIVES_DIR, { recursive: true });
+} else {
+  console.log(`[Server] Archives directory exists.`);
+}
+
+app.use(express.json());
+
+// API: List archives (subdirectories in ARCHIVES_DIR)
+app.get('/api/archives', (req, res) => {
+  try {
+    console.log(`[API] Listing archives from ${ARCHIVES_DIR}...`);
+    const items = fs.readdirSync(ARCHIVES_DIR, { withFileTypes: true });
+    console.log(`[API] Found ${items.length} total items in archives directory.`);
+    
+    const archives = items
+      .filter(item => {
+        const isDir = item.isDirectory();
+        if (!isDir) console.log(`[API] Skipping non-directory: ${item.name}`);
+        return isDir;
+      })
+      .map(item => {
+        // Try to find a profile pic or first image for the thumbnail
+        const archivePath = path.join(ARCHIVES_DIR, item.name);
+        const files = fs.readdirSync(archivePath);
+        console.log(`[API] Found archive: ${item.name} (${files.length} files)`);
+        
+        let thumbnail = '';
+        const profilePic = files.find(f => f.toLowerCase().includes('_profile_pic.jpg') || f.toLowerCase() === `${item.name.toLowerCase()}.jpg`);
+        if (profilePic) {
+          thumbnail = `/archives/${item.name}/${profilePic}`;
+        } else {
+          const firstImage = files.find(f => /\.(jpg|jpeg|png|webp)$/i.test(f));
+          if (firstImage) thumbnail = `/archives/${item.name}/${firstImage}`;
+        }
+
+        return {
+          name: item.name,
+          thumbnail,
+          path: item.name,
+          fileCount: files.length
+        };
+      });
+    
+    console.log(`[API] Returning ${archives.length} validated archives.`);
+    res.json(archives);
+  } catch (err) {
+    console.error('[API] Error listing archives:', err);
+    res.status(500).json({ error: 'Failed to list archives' });
+  }
+});
+
+// API: List all files in an archive (recursive)
+app.get('/api/archives/:name/files', (req, res) => {
+  const archiveName = req.params.name;
+  const archivePath = path.join(ARCHIVES_DIR, archiveName);
+
+  if (!fs.existsSync(archivePath)) {
+    return res.status(404).json({ error: 'Archive not found' });
+  }
+
+  try {
+    const walk = (dir: string, base: string = ''): string[] => {
+      let results: string[] = [];
+      const list = fs.readdirSync(dir);
+      list.forEach(file => {
+        const filePath = path.join(dir, file);
+        const relativePath = path.join(base, file);
+        const stat = fs.statSync(filePath);
+        if (stat && stat.isDirectory()) {
+          results = results.concat(walk(filePath, relativePath));
+        } else {
+          results.push(relativePath);
+        }
+      });
+      return results;
+    };
+
+    const files = walk(archivePath);
+    res.json(files);
+  } catch (err) {
+    console.error('Error listing files:', err);
+    res.status(500).json({ error: 'Failed to list files' });
+  }
+});
+
+// Serve archive files
+app.use('/archives', express.static(ARCHIVES_DIR));
+
+// Serve production frontend
+const distPath = path.join(__dirname, 'dist');
+if (fs.existsSync(distPath)) {
+  app.use(express.static(distPath));
+  app.get('*', (req, res) => {
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+}
+
+app.listen(PORT, () => {
+  console.log(`Server running at http://localhost:${PORT}`);
+  console.log(`Serving archives from: ${ARCHIVES_DIR}`);
+});

vite.config.ts

@@ -64,8 +64,12 @@ export default defineConfig(({mode}) => {
     },
     server: {
       // HMR is disabled in AI Studio via DISABLE_HMR env var.
-      // Do not modify—file watching is disabled to prevent flickering during agent edits.
+      // Do not modify—file watching is disabled to prevent flickering during agent edits.
       hmr: process.env.DISABLE_HMR !== 'true',
+      proxy: {
+        '/api': 'http://localhost:3001',
+        '/archives': 'http://localhost:3001',
+      },
     },
   };
 });