📸 Instagram Saved Posts Tracker

A modern, self-hosted web app to archive, monitor, and explore your Instagram saved posts.

⚡ Quick Start • 🚀 Deploy on PaaS • ✨ Key Features • 📖 Documentation • 🛠️ Configuration

---

🌟 Overview

Instagram doesn't provide a native search or long-term archive for your saved posts. When creators delete their accounts, change handles, or make posts private, you lose access to bookmarked content.

Instagram Saved Posts Tracker solves this by giving you full ownership over your bookmarks:

• 🔄 Continuous Sync & Archival: Scrapes and stores saved posts, carousel media, captions, and account metadata.
• 👥 Multi-Profile Switching: Netflix-style profile selector supporting multiple Instagram accounts simultaneously.
• 🕒 Account Timeline & History: Detects when accounts change usernames, lose verification, get deleted/banned, or go private.
• 🚀 1-Command Zero-Config Deploy: Start with a single terminal command or deploy directly to Dokploy / Coolify.

---

⚡ Quick Start (1 Command)

No clone, build, or manual .env configuration needed. Run the one-liner for your operating system:

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/gitnasr/Instagram-Saved-Posts/master/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/gitnasr/Instagram-Saved-Posts/master/install.ps1 | iex

Docker Compose

Create a docker-compose.yml file and launch:

services:
  app:
    image: ghcr.io/gitnasr/instagram-saved-posts:latest
    pull_policy: always
    restart: unless-stopped
    ports:
      - "5050:3000"
    environment:
      - DATABASE_URL=mongodb://mongo:27017/instagram?replicaSet=rs0&directConnection=true
    depends_on:
      mongo:
        condition: service_healthy

  mongo:
    image: mongo:7.0
    restart: unless-stopped
    command: ["--replSet", "rs0", "--bind_ip_all", "--port", "27017"]
    volumes:
      - mongo_data:/data/db
    healthcheck:
      test: >
        mongosh --port 27017 --eval "
          try {
            rs.status().ok
          } catch (e) {
            rs.initiate({
              _id: 'rs0',
              members: [{ _id: 0, host: 'mongo:27017' }]
            }).ok
          }
        " || exit 1
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 2s

volumes:
  mongo_data:

docker compose up -d

🎉 Open http://localhost:5050 in your browser and complete the 60-second onboarding wizard!

Optional: AI Vector Search (Beta). Semantic prompt, image and face search is not enabled by default — it adds a Qdrant service and downloads ~600 MB of model weights on first index. Everything else works fine without it. To opt in, grab docker-compose.search.yml and run:

docker compose -f docker-compose.yml -f docker-compose.search.yml up -d

Full setup and trade-offs: AI Vector Search.

---

🚀 1-Click PaaS Deployment

Deploy easily to your self-hosted cloud platform of choice:

Dokploy

1. In Dokploy, click Create Project -> Compose.
2. Copy and paste the contents of dokploy-compose.yml.
3. Set your custom domain and click Deploy.
4. Read the Dokploy Deployment Guide for full instructions.

Coolify

1. In Coolify, create a New Resource -> Docker Compose.
2. Paste the contents of coolify-compose.yml.
3. Configure your domain and click Deploy.
4. Read the Coolify Deployment Guide for detailed configuration.

---

📦 Versioning, Releases & Rollbacks

This project follows an automated semantic CI/CD versioning lifecycle directly connected to GitHub Releases:

• Production (:latest): Every release merged to main/master automatically calculates the semantic version bump, generates a signed Git tag (e.g., v1.1.0), publishes a GitHub Release with auto-generated changelogs, and pushes to GHCR.
• Rollbacks & Version Pinning: Every release tag is permanently archived on GitHub Container Registry (GHCR). To rollback or pin a version, simply replace :latest with the desired release tag in your compose configuration:

  # Pin or rollback to any version:
  image: ghcr.io/gitnasr/instagram-saved-posts:v1.0.1

  Check the GitHub Releases Page for the full list of tags and version notes.
• PR Beta Versions: Pull requests automatically build preview beta containers tagged as ghcr.io/gitnasr/instagram-saved-posts:beta-pr-<number> and :beta for preview testing before merging.

---

Feature	Description
🔍 Multimodal Vector Search (Beta, optional)	Natural-language prompt search (CLIP), visual similarity image search, and facial recognition search with Qdrant. Off by default — how to enable.
🧙‍♂️ Interactive Onboarding	Built-in setup wizard with real-time Instagram cookie testing and avatar preview.
👥 Multi-Profile Support	Manage multiple Instagram accounts with separate sessions and isolated bookmarks.
📈 Account Timelines	Automatically records username changes, bio updates, verification changes, and lost accounts.
🛡️ Resumable Scraper	Automatic rate-limit detection, exponential backoff, and checkpointed resume support.
☁️ Permanent Media CDN	Optional Cloudinary sync to ensure media URLs never break when Instagram CDN links expire.
🔐 Reverse Proxy & SSO	Native support for Authentik / Authelia headers with read-only viewer mode.
🌙 Dark & Light Mode	Modern, responsive UI built with Tailwind CSS v4 and Radix UI.

---

📖 Documentation

Comprehensive guides and interactive documentation are hosted on the Documentation Website and maintained in the /docs directory as the single source of truth:

• 🌐 Interactive Documentation Website
• 🔑 How to Get Your Instagram Cookie
• 🐳 Docker Compose Deployment Guide
• 🟣 Dokploy Self-Hosting Guide
• 🔷 Coolify Self-Hosting Guide
• 🔒 Reverse Proxy & Authentik SSO Guide
• ☁️ Cloudinary Permanent CDN Setup
• 💾 Backup & Database Migration
• ❓ Troubleshooting & FAQ

---

🛠️ Configuration

When running via Docker Compose, zero environment variables are required. Optional settings can be configured via .env:

Variable	Default	Description
PORT	5050	Port exposed on host for web app
QDRANT_URL	(unset)	Optional. Setting this switches on the beta vector search. Unset = disabled
QDRANT_PORT	6335	Host port for the Qdrant API & Dashboard, only used with search enabled
DATABASE_URL	mongodb://mongo:27017/instagram?replicaSet=rs0&directConnection=true	MongoDB connection string (replica set enabled)
CLOUDINARY_CLOUD_NAME	""	Optional Cloudinary cloud name for permanent media
CLOUDINARY_API_KEY	""	Optional Cloudinary API key
CLOUDINARY_API_SECRET	""	Optional Cloudinary API secret
LOG_LEVEL	info	Logging verbosity (info, debug, warn, error)

---

🧑‍💻 Local Development

# 1. Clone repository
git clone https://github.com/gitnasr/Instagram-Saved-Posts.git
cd Instagram-Saved-Posts

# 2. Install dependencies
npm install

# 3. Start local MongoDB with replica set (required for Prisma transactions)
docker run -d -p 27017:27017 --name ig_mongo mongo:7.0 --replSet rs0
docker exec ig_mongo mongosh --eval "rs.initiate()"

# 4. Generate Prisma client & start dev server
export DATABASE_URL="mongodb://localhost:27017/instagram?replicaSet=rs0&directConnection=true"
npx prisma generate
npm run dev

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Check out CONTRIBUTING.md for development guidelines.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.