Files

T

ergosteurandClaude Opus 5 f53c47a5ef docs: move the branch warning into a TOOLING.md that main does not have

Putting it at the top of README.md worked, but it diverged a shared file: a
probe showed main editing the adjacent line conflicts on every merge. The
warning survived the conflict, so nothing was ever silently lost, but a file
that only exists on this branch has no such cost at all.

TOOLING.md carries the warning plus what CLAUDE.md would have said if it could
— the commands, the remote policy, and the two guards, which are local and
unversioned and so are absent from every fresh clone.

Shared files are byte-identical to main again: CLAUDE.md, README.md and
package.json. The divergence is now only files main has never had.

Trade-off worth knowing: gitea renders README.md on the branch page and does
not render TOOLING.md, so this warning is one click less visible than it was.
The pre-push hook, not the documentation, remains the guard that actually
stops a mistake.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UXfdJu7QhSJLr47K7koTDF

2026-08-20 16:36:22 -04:00

4.6 KiB

Raw Permalink Blame History

InstaArchive Viewer

A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives.

Features

Advanced Carousel: Seamless, zero-latency transitions between slides with intelligent preloading. Navigating between different posts is now near-instant thanks to inter-post background preloading.
High-Res Performance: Handles 50MP+ images effortlessly using a background Web Worker and a memory-safe serial processing queue.
Persistent Local Caching: Uses IndexedDB to store parsed archives and generated thumbnails. Local folders now load instantly from cache on return visits without needing to re-upload files.
Permalinks: State is synchronized with the URL, allowing you to share direct links to archives, tabs, or specific posts. Navigating back to the explorer cleans up URL parameters automatically.
Glassy Scanning UI: A refined, translucent white terminal experience with flicker-free, double-buffered dynamic blurred backgrounds.
PWA with Auto-Update: Fully offline-capable and installable. Clients automatically receive updates when a new version is deployed to the server.
Local Privacy: All processing is done client-side. Even when using the self-hosted version, your media is processed locally in your browser and never uploaded.
Smart Fallbacks: Automatically detects usernames from folder names and uses the oldest archive image as a profile picture if one is missing.
Customizable Grid: 1:1 or 3:4 aspect ratios with adjustable "bumps" for aesthetic alignment.
Story Viewer: Native-like story experience with segmented progress bars, auto-playback, and audio controls.
Navigation Protection: Intercepts accidental browser "Back" or "Refresh" actions to protect your current session.

Deployment

Docker (Recommended)

The easiest way to run InstaArchive is using Docker.

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:

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:

Check Directory Permissions: Ensure the archive folder is world-readable:
```
chmod -R 755 /path/to/archives
```
SELinux (Fedora/RHEL/CentOS): Use the :z flag in your volume mount as shown above.
User Mapping: The container runs as the non-root node user (UID 1000). If your archives are readable only by another account, run as that user instead — the container needs to list the archive directory, so --x (traverse-only) permissions are not enough:
```
docker run --user $(stat -c '%u:%g' /path/to/archives) ...
```
In Compose:
```
services:
  instaarchive:
    user: "1234:1234"   # a UID that can read your archives
```

Archive Index

On first start the server walks the archive root once and caches the result, keyed by directory mtime. This matters on network storage: for a 110k-file archive root, listing went from ~52s per request to ~0.1s. Mount a volume at /cache (or set CACHE_DIR) so the index survives restarts, otherwise it is rebuilt on every start.

Supported Archive Structure

Place your archive folders inside the mounted /archives directory. The directory name will be used as the account username.

Example Structure:

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)

Install dependencies: npm install
Start dev server: npm run dev (Frontend on port 3000)
Start local backend: npm run server (Optional, serves ./_sample-archives on port 3001)
Build production: npm run build (Generates ./dist for frontend and ./dist-server for the API)

4.6 KiB Raw Permalink Blame History