fix: address Docker EACCES errors with better logging and SELinux hints

Dockerfile

@@ -7,7 +7,7 @@ WORKDIR /app
 COPY package*.json ./
 RUN npm ci
 
-# Copy source and build frontend
+# Copy source and build (frontend and server)
 COPY . .
 RUN npm run build
 
@@ -27,12 +27,12 @@ RUN npm ci --omit=dev
 
 # Copy built assets and server
 COPY --from=build /app/dist ./dist
-COPY --from=build /app/server.ts ./
+COPY --from=build /app/dist-server/server.js ./server.js
 
 # Ensure archives directory exists
 RUN mkdir -p /archives
 
 EXPOSE 3000
 
-# Start server using tsx
+# Start server
-CMD ["npx", "tsx", "server.ts"]
+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,78 @@ 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
+```
+
+> **Note for Linux/SELinux users:** If you see "Permission Denied" in the logs, append `,z` to your volume mount: `-v /path/to/archives:/archives:ro,z`
+
+### Docker Compose
+
+Create a `compose.yml` file:
+
+```yaml
+services:
+  instaarchive:
+    image: ghcr.io/ergosteur/instaarchive-viewer:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./archives:/archives:ro,z # ,z handles SELinux permissions
+```
+
+### Troubleshooting Permissions
+
+If the app shows "No Archives Found" and logs `EACCES: permission denied`:
+
+1. **Check Directory Permissions**: Ensure the archive folder is world-readable:
+   ```bash
+   chmod -R 755 /path/to/archives
+   ```
+2. **SELinux (Fedora/RHEL/CentOS)**: Use the `:z` flag in your volume mount as shown above.
+3. **User Mapping**: You can force the container to run as your host user:
+   ```bash
+   docker run --user $(id -u):$(id -g) ...
+   ```
+
+## 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,11 @@
+services:
+  instaarchive:
+    image: ghcr.io/ergosteur/instaarchive-viewer:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./archives:/archives:ro,z
+    environment:
+      - PORT=3000
+      - ARCHIVES_DIR=/archives
+    restart: unless-stopped

package.json

@@ -1,11 +1,12 @@
 {
   "name": "react-example",
   "private": true,
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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",

server.ts

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import dotenv from 'dotenv';
+import os from 'os';
 
 dotenv.config();
 
@@ -11,12 +12,23 @@ const __dirname = path.dirname(__filename);
 
 const app = express();
 const PORT = process.env.PORT || 3001;
-const ARCHIVES_DIR = process.env.ARCHIVES_DIR || path.join(__dirname, '_sample-archives');
+const ARCHIVES_DIR = path.resolve(process.env.ARCHIVES_DIR || path.join(__dirname, '_sample-archives'));
+
+console.log(`[Server] Initializing...`);
+console.log(`[Server] Running as user: ${os.userInfo().username} (UID: ${os.userInfo().uid}, GID: ${os.userInfo().gid})`);
+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(`Warning: Archives directory not found at ${ARCHIVES_DIR}. Creating it...`);
+  console.warn(`[Server] Warning: Archives directory not found at ${ARCHIVES_DIR}. Creating it...`);
+  try {
     fs.mkdirSync(ARCHIVES_DIR, { recursive: true });
+  } catch (err) {
+    console.error(`[Server] Failed to create archives directory:`, err);
+  }
+} else {
+  console.log(`[Server] Archives directory exists.`);
 }
 
 app.use(express.json());
@@ -24,13 +36,22 @@ 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 => item.isDirectory())
+      .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);
+        try {
           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`);
@@ -47,11 +68,23 @@ app.get('/api/archives', (req, res) => {
             path: item.name,
             fileCount: files.length
           };
-      });
+        } catch (e) {
+          console.error(`[API] Could not read subdirectory ${item.name}:`, e);
+          return null;
+        }
+      })
+      .filter(Boolean);
+    
+    console.log(`[API] Returning ${archives.length} validated archives.`);
     res.json(archives);
-  } catch (err) {
+  } catch (err: any) {
-    console.error('Error listing archives:', err);
+    if (err.code === 'EACCES') {
-    res.status(500).json({ error: 'Failed to list archives' });
+      console.error(`[API] Permission Denied! The server (UID ${os.userInfo().uid}) cannot read ${ARCHIVES_DIR}.`);
+      console.error(`[API] Hint: If using Linux/Docker, check folder permissions (chmod 755) or SELinux context (append :z to your volume mount).`);
+    } else {
+      console.error('[API] Error listing archives:', err);
+    }
+    res.status(500).json({ error: 'Permission denied or failed to list archives' });
   }
 });