ergosteurandClaude Opus 5
f53c47a5ef
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
104 lines
4.6 KiB
Markdown
104 lines
4.6 KiB
Markdown
# 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.
|
|
|
|
```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**: 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:
|
|
```bash
|
|
docker run --user $(stat -c '%u:%g' /path/to/archives) ...
|
|
```
|
|
In Compose:
|
|
```yaml
|
|
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:
|
|
```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:** `npm install`
|
|
2. **Start dev server:** `npm run dev` (Frontend on port 3000)
|
|
3. **Start local backend:** `npm run server` (Optional, serves `./_sample-archives` on port 3001)
|
|
4. **Build production:** `npm run build` (Generates `./dist` for frontend and `./dist-server` for the API)
|