docs: rewrite README with accurate stats, schema docs, and category breakdown

2026-04-23 17:25:14 +02:00 · 2026-04-18 20:26:17 +05:30
parent d26debb71e
commit 505d715ca7
1 changed files with 199 additions and 156 deletions
--- a/README.md
+++ b/README.md
@@ -1,191 +1,234 @@
-<p align="center">
-  <img src="assets/logo.png" alt="The Alt Stack" width="120" />
-</p>
+<div align="center">

-<h1 align="center">Awesome Open Source Alternatives - The AltStack Data HQ</h1>
+# The AltStack — Data HQ

-<p align="center">
-  <strong>A curated list of 450+ open-source alternatives to popular SaaS products.</strong><br />
-  Stop paying for what you can host yourself. Build sovereign infrastructure with AltStack.
-</p>
+### The open dataset behind [thealtstack.com](https://thealtstack.com)

-<p align="center">
-  <a href="https://github.com/altstackHQ/altstack-data/stargazers"><img src="https://img.shields.io/github/stars/altstackHQ/altstack-data?color=ffdd00&label=Stars&logo=github&style=for-the-badge" alt="GitHub stars" /></a>
-  <a href="https://github.com/altstackHQ/altstack-data/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge&logo=apache" alt="License" /></a>
-  <a href="https://github.com/altstackHQ/altstack-data/issues"><img src="https://img.shields.io/badge/PRs-Welcome-brightgreen?style=for-the-badge&logo=git&logoColor=white" alt="PRs Welcome" /></a>
-</p>
+**488 open-source tools · 32 categories · 352 AI models · 68 Docker deploy configs**

-<p align="center">
-  <a href="https://thealtstack.com"><strong>Explore the Directory</strong></a> •
-  <a href="https://thealtstack.com/self-hosted"><strong>Self-Hosted Configurator</strong></a> •
-  <a href="https://docs.thealtstack.com"><strong>Self-Hosting Guides</strong></a> •
-  <a href="https://github.com/altstackHQ/altstack-data/issues"><strong>Request a Tool</strong></a>
-</p>
+[![Live Directory](https://img.shields.io/badge/Browse-thealtstack.com-ef4444?style=for-the-badge&logo=vercel&logoColor=white)](https://thealtstack.com)
+[![Main Repo](https://img.shields.io/badge/Frontend-aa--humaaan/thealtstack-0ea5e9?style=for-the-badge&logo=github)](https://github.com/aa-humaaan/thealtstack)
+[![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-22c55e?style=for-the-badge)](LICENSE)
+
+</div>

 ---

-## 🚀 Why Sovereign Infrastructure?
+## What is this repo?

-Every SaaS you pay for is a piece of your sovereign control you are leasing. The mission of **AltStack** is to provide the data and deployment configurations necessary to replace the "Big Tech" stack with a **Sovereign Stack** you own.
+This is the **data layer** for [The AltStack](https://thealtstack.com) — a curated directory of open-source alternatives to popular SaaS products. Everything the website displays comes from the files in this repo:

-This repository serves as the **Data HQ** for [The AltStack](https://thealtstack.com). Every tool listed here is vetted for quality, activity, and self-hostability. See [CRITERIA.md](CRITERIA.md) for the full vetting standards.
+- The full tool database (`tools.json`)
+- Docker Compose deployment configs for 68+ tools
+- Blog content and editorial copy
+- Category descriptions and SEO metadata
+- Curated "Stack" bundles (pre-built tool combos for common use cases)

-## 🚀 Quick Start (Mini-Stacks)
+If you want to add a tool, fix a description, or contribute a Docker config — this is where you do it.

-Get up and running in under 2 minutes. These are "Development Mode" snippets. For production-hardened setups (SSL, Backups, Auth), follow the links to The AltStack Documentation.
+---
+
+## Repository Structure

-### 📦 PocketBase (BaaS)
-The fastest way to get a backend with Auth, Database, and Admin UI.
-```yaml
-# docker-compose.yml
-services:
-  pocketbase:
-    image: mujo-code/pocketbase:latest
-    container_name: pocketbase
-    ports:
-      - "8090:8080"
-    volumes:
-      - ./pb_data:/pb_data
-    restart: unless-stopped
 ```
-👉 [Open in Self-Hosted Configurator](https://thealtstack.com/self-hosted/pocketbase) • [Deployment Guide](https://docs.thealtstack.com/deploy/pocketbase)
-
-### 📊 Plausible Analytics (Privacy-First)
-Lightweight, open-source analytics.
-```yaml
-# docker-compose.yml (Simplified)
-services:
-  plausible:
-    image: plausible/analytics:latest
-    ports:
-      - "8000:8000"
-    env_file: .env
-...
+├── data/
+│   ├── tools.json              # The master database — 488 tools, every field
+│   ├── tools-min.json          # Minified version (client-side, faster loads)
+│   ├── tools_expanded.json     # Expanded version with enriched metadata
+│   ├── blog-posts.ts           # Blog post content (15 articles)
+│   ├── stacks.ts               # Curated stack definitions (5 bundles)
+│   ├── category_editorial.json # Category descriptions, SEO copy, editorial
+│   ├── memory.json             # Sentinel pipeline state & run history
+│   └── seo.ts                  # Global SEO configuration
+├── docker-deploy/              # 68 Docker Compose configs + install scripts
+│   ├── supabase/
+│   │   ├── docker-compose.yml
+│   │   └── install.sh
+│   ├── n8n/
+│   ├── plausible/
+│   ├── mattermost/
+│   └── ... (68 tools total)
+├── deployments/                # Deployment metadata & generated configs
+├── docs/                       # Documentation site source (Nextra)
+├── scraper/                    # Python scraper for data enrichment
+│   ├── scraper.py
+│   └── requirements.txt
+├── scripts/
+│   └── fetch-github-metadata.js  # GitHub stars/activity enrichment
+├── assets/                     # Logos and static assets
+├── CONTRIBUTING.md             # How to contribute
+├── CRITERIA.md                 # Tool vetting standards
+├── CODE_OF_CONDUCT.md          # Community guidelines
+└── LICENSE                     # CC BY 4.0
 ```
-👉 [Open in Self-Hosted Configurator](https://thealtstack.com/self-hosted/plausible) • [Full Self-Hosting Guide](https://docs.thealtstack.com/deploy/plausible)

 ---

-## 🛠️ Browse by Category
+## The Data: `tools.json`

- [🏗️ Backend as a Service](#-backend-as-a-service-baas) → [Compare all on thealtstack.com](https://thealtstack.com/best/backend-as-a-service)
- [💬 Communication](#-communication--collaboration) → [Compare all on thealtstack.com](https://thealtstack.com/best/communication)
- [📊 Analytics & BI](#-analytics--bi) → [Compare all on thealtstack.com](https://thealtstack.com/best/analytics)
- [📁 Project Management](#-project-management) → [Compare all on thealtstack.com](https://thealtstack.com/best/project-management)
+The core of this repo. Each tool entry looks like this:
+
+```json
+{
+  "slug": "plausible",
+  "name": "Plausible Analytics",
+  "category": "Analytics",
+  "is_open_source": true,
+  "pricing_model": "Free Self-Hosted / Paid Cloud",
+  "website": "https://plausible.io",
+  "description": "Lightweight and privacy-friendly Google Analytics alternative.",
+  "alternatives": ["Google Analytics", "Mixpanel"],
+  "tags": ["analytics", "privacy", "self-hosted"],
+  "logo_url": "https://...",
+  "avg_monthly_cost": 0,
+  "pros": ["Privacy-first", "Lightweight script", "Easy to self-host"],
+  "cons": ["Fewer advanced features than GA4"]
+}
+```
+
+### Categories (32)
+
+| Category | Tools | Category | Tools |
+|---|---|---|---|
+| AI Models | 352 | Productivity | 16 |
+| DevOps | 9 | Marketing | 9 |
+| Security | 9 | Analytics | 8 |
+| Cloud Infrastructure | 5 | Communication | 5 |
+| Design | 5 | Backend as a Service | 4 |
+| CRM | 4 | Automation | 4 |
+| Support | 4 | AI Coding | 3 |
+| AI Image Generation | 3 | CAD | 3 |
+| ERP | 3 | Project Management | 3 |
+| AI Interfaces | 2 | AI Video Generation | 2 |
+| AI Tools | 2 | API Development | 2 |
+| Creative | 2 | E-commerce | 2 |
+| Email | 2 | Financial | 2 |
+| HR | 2 | Legal | 2 |
+| AI Runners | 4 | Monitoring | 6 |
+| Photos | 1 | Uncategorized | 8 |

 ---

-## 📂 The Awesome Alternatives List
+## Docker Deploy Configs

-### 🏗️ Backend as a Service (BaaS)
-*Alternatives to **Firebase** and **AWS Amplify***
- **[Supabase](https://github.com/supabase/supabase)** - The open source Firebase alternative with a dedicated Postgres database.
- **[Appwrite](https://github.com/appwrite/appwrite)** - A complete backend for Flutter, Web, and Mobile developers.
- **[PocketBase](https://github.com/pocketbase/pocketbase)** - Open source realtime backend in 1 file (Go & SQLite).
- [🔗 **Compare BaaS Alternatives on AltStack**](https://thealtstack.com/best/backend-as-a-service)
-
-### 💬 Communication & Collaboration
-*Alternatives to **Slack**, **Zoom**, and **Microsoft Teams***
- **[Mattermost](https://github.com/mattermost/mattermost)** - Open source platform for secure collaboration across the SDLC.
- **[Rocket.Chat](https://github.com/RocketChat/Rocket.Chat)** - The Secure CommsOS™ for mission-critical operations.
- **[Jitsi Meet](https://github.com/jitsi/jitsi-meet)** - Fully encrypted, 100% open source video conferencing.
- [🔗 **Explore Communication Stacks on AltStack**](https://thealtstack.com/best/communication)
-
-### 📊 Analytics & BI
-*Alternatives to **Google Analytics**, **Mixpanel**, and **Tableau***
- **[Plausible](https://github.com/plausible/analytics)** - Simple, lightweight, and privacy-friendly web analytics.
- **[PostHog](https://github.com/PostHog/posthog)** - Product analytics, session recording, and feature flags.
- **[Matomo](https://github.com/matomo-org/matomo)** - The leading open source Google Analytics alternative.
- **[Metabase](https://github.com/metabase/metabase)** - The simplest way to get business intelligence throughout your company.
- **[Apache Superset](https://github.com/apache/superset)** - Modern data exploration and visualization platform.
- [🔗 **Check Analytics on AltStack**](https://thealtstack.com/best/analytics)
-
-### 📁 Project Management
-*Alternatives to **Jira**, **Asana**, and **Monday.com***
- **[Plane](https://github.com/makeplane/plane)** - Beautiful open-source Jira/Linear alternative.
- **[Taiga](https://github.com/taigaio/taiga-back)** - Agile project management for multi-functional teams.
- **[OpenProject](https://github.com/opf/openproject)** - Powerful classic project management and collaboration.
- [🔗 **Self-host Project Management on AltStack**](https://thealtstack.com/best/project-management)
-
-### 🎨 Design & Creative
-*Alternatives to **Photoshop**, **Figma**, and **Illustrator***
- **[Penpot](https://github.com/penpot/penpot)** - The open-source design tool for design and code collaboration (Figma alternative).
- **[GIMP](https://github.com/GNOME/gimp)** - Professional-grade photo editing tools (Photoshop alternative).
- **[Krita](https://github.com/KDE/krita)** - Open source digital painting (Illustrator/Corel alternative).
- [🔗 **Design Tools on AltStack**](https://thealtstack.com/best/design)
-
-### 📝 Productivity & Knowledge
-*Alternatives to **Notion**, **Microsoft 365**, and **Google Workspace***
- **[AppFlowy](https://github.com/AppFlowy-IO/AppFlowy)** - Privacy-focused Notion alternative built in Rust.
- **[AFFiNE](https://github.com/toeverything/AFFiNE)** - Next-gen knowledge base that brings planning and creation together.
- **[ONLYOFFICE](https://github.com/ONLYOFFICE/DocumentServer)** - Highly compatible MS Office online editors.
- [🔗 **Productivity Alternatives on AltStack**](https://thealtstack.com/best/productivity)
-
-### 🔐 Security & IAM
-*Alternatives to **1Password**, **Auth0**, and **Okta***
- **[Bitwarden](https://github.com/bitwarden/server)** - Open source password manager for individuals and teams.
- **[KeePassXC](https://github.com/keepassxreboot/keepassxc)** - Fully offline, AES-256 password manager.
- **[Keycloak](https://github.com/keycloak/keycloak)** - Open source identity and access management.
- **[Authentik](https://github.com/goauthentik/authentik)** - The overall-best open-source identity provider.
- [🔗 **Security Tools on AltStack**](https://thealtstack.com/best/security)
-
-### 🛠️ DevOps & Automation
-*Alternatives to **Heroku**, **Zapier**, and **Vercel***
- **[Coolify](https://github.com/coollabsio/coolify)** - Self-hostable PaaS alternative to Heroku & Netlify.
- **[n8n](https://github.com/n8n-io/n8n)** - Workflow automation tool with 400+ integrations.
- **[Activepieces](https://github.com/activepieces/activepieces)** - Open source Zapier alternative.
- [🔗 **DevOps Tools on AltStack**](https://thealtstack.com/best/devops)
-
-### 💾 Storage & Infrastructure
-*Alternatives to **AWS S3**, **Dropbox**, and **Salesforce***
- **[Garage](https://github.com/deuxfleurs-org/garage)** - An open-source distributed object storage service tailored for self-hosting.
- **[Odoo](https://github.com/odoo/odoo)** - All-in-one ERP suite (Salesforce alternative).
- **[Nextcloud](https://github.com/nextcloud/server)** - Content collaboration platform (Dropbox/Google Drive alternative).
- [🔗 **Infrastructure on AltStack**](https://thealtstack.com/best/cloud-infrastructure)
-
---
-
-## ⚡ Quick Start: Deploy Your First Alternative
-
-Most tools in this list can be deployed in minutes using Docker. Here is how to get started with the AltStack approach:
-
-1. **Clone this repo**: `git clone https://github.com/altstackHQ/altstack-data.git`
-2. **Explore `/deployments`**: Find the Docker Compose file for the tool you want.
-3. **Go Sovereign**: Visit [docs.thealtstack.com](https://docs.thealtstack.com) for production-hardened guides (SSL, backups, and reverse proxies).
-
-> [!TIP]
-> This repository contains basic community configs. For commercial-grade Sovereign Infrastructure setup, always refer to our [Official Documentation](https://docs.thealtstack.com).
+Every config in `docker-deploy/` is a ready-to-use `docker-compose.yml` with an accompanying `install.sh` script. Just clone and run:

 ```bash
-cd deployments/plausible
-docker-compose up -d
+cd docker-deploy/plausible
+chmod +x install.sh
+./install.sh
+```
+
+Or copy the `docker-compose.yml` directly:
+
+```bash
+cd docker-deploy/n8n
+docker compose up -d
+```
+
+Currently covering **68 tools** including: Supabase, Mattermost, Plausible, PostHog, Keycloak, N8N, Immich, Authentik, Metabase, Plane, and many more.
+
+> **Want to add a config?** See [CONTRIBUTING.md](CONTRIBUTING.md). We test every config before merging.
+
+---
+
+## Curated Stacks
+
+Pre-built tool bundles for common use cases, defined in `data/stacks.ts`:
+
+| Stack | What it's for | Monthly savings |
+|---|---|---|
+| 🚀 **The Bootstrapper** | Full SaaS toolkit for solo founders | ~$310/mo |
+| 🎨 **The Designer** | Adobe Creative Cloud replacement | ~$110/mo |
+| 🛡️ **The Privacy Stack** | De-Google your life | ~$80/mo |
+| 🏢 **The Enterprise** | Full office suite replacement | ~$250/mo |
+| 🤖 **The AI Stack** | Self-hosted AI/ML infrastructure | ~$200/mo |
+
+---
+
+## How the Data Stays Fresh
+
+This repo is kept up-to-date by an automated pipeline (the "Sentinel Engine") that runs nightly via GitHub Actions:
+
+1. **Discovery** — Scans GitHub trending, Hacker News, and community submissions for new tools
+2. **Validation** — Checks existing entries for dead links, archived repos, and stale projects
+3. **Enrichment** — Pulls latest GitHub stars, activity metrics, and metadata
+4. **Docker generation** — Auto-generates Docker Compose configs for newly added tools
+5. **Content** — Generates blog posts, tool reviews, and comparison pages
+
+The pipeline opens PRs automatically so everything gets reviewed before merging.
+
+---
+
+## Contributing
+
+We welcome contributions! The most impactful ways to help:
+
+### Add a new tool
+1. Fork this repo
+2. Add a new entry to `data/tools.json` following the schema above
+3. Make sure it meets our [vetting criteria](CRITERIA.md)
+4. Open a PR
+
+### Add a Docker config
+1. Create a new folder in `docker-deploy/` named after the tool's slug
+2. Add a `docker-compose.yml` and an `install.sh`
+3. Test it locally — it should produce a working deployment
+4. Open a PR
+
+### Fix data
+Found a broken link, wrong pricing, or outdated description? Edit `data/tools.json` and open a PR. Small, targeted fixes are the fastest to merge.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## Using the Data
+
+The data in this repo is licensed under [CC BY 4.0](LICENSE). You're free to use it in your own projects — just give attribution.
+
+### Fetch the raw JSON
+
+```bash
+# Full database
+curl -O https://raw.githubusercontent.com/altstackHQ/altstack-data/main/data/tools.json
+
+# Minified (smaller, for client-side use)
+curl -O https://raw.githubusercontent.com/altstackHQ/altstack-data/main/data/tools-min.json
+```
+
+### Use in JavaScript/TypeScript
+
+```ts
+const response = await fetch(
+  'https://raw.githubusercontent.com/altstackHQ/altstack-data/main/data/tools.json'
+);
+const tools = await response.json();
+
+// Filter by category
+const analytics = tools.filter(t => t.category === 'Analytics');
+
+// Find alternatives to a specific SaaS
+const slackAlts = tools.filter(t => 
+  t.alternatives?.includes('Slack')
+);
 ```

 ---

-## 🗺️ Directory Mapping (The AltStack Bridge)
+## Links

-We use the data in this repository to power our [Main Website](https://thealtstack.com). Here is how the categories map:
-
-| UI Directory | Data Source (this repo) | Self-Hosted Guide |
-| :--- | :--- | :--- |
-| [Backend](https://thealtstack.com/best/backend-as-a-service) | `data/tools.json` | [Deploy Guides](https://docs.thealtstack.com/deploy/supabase) |
-| [Analytics](https://thealtstack.com/best/analytics) | `data/tools.json` | [Deploy Guides](https://docs.thealtstack.com/deploy/plausible) |
-| [Project Management](https://thealtstack.com/best/project-management) | `data/tools.json` | [Deploy Guides](https://docs.thealtstack.com/deploy/plane) |
-| [Communication](https://thealtstack.com/best/communication) | `data/tools.json` | [Deploy Guides](https://docs.thealtstack.com/deploy/mattermost) |
-| [Productivity](https://thealtstack.com/best/productivity) | `data/tools.json` | [Deploy Guides](https://docs.thealtstack.com/deploy/appflowy) |
+- 🌐 **Website**: [thealtstack.com](https://thealtstack.com)
+- 💻 **Frontend repo**: [aa-humaaan/thealtstack](https://github.com/aa-humaaan/thealtstack)
+- 🐛 **Report an issue**: [Open an issue](https://github.com/altstackHQ/altstack-data/issues)
+- 📬 **Request a tool**: [Open an issue](https://github.com/altstackHQ/altstack-data/issues/new)

 ---

-## 🤝 Contributing
+<div align="center">

-We love contributions! If you know of a great open-source tool we missed:
-1. Check the [Contribution Guidelines](CONTRIBUTING.md).
-2. Open an Issue with the tool details.
-3. Submit a PR to update `data/tools.json`.
+**Built by [@aa-humaaan](https://github.com/aa-humaaan)**

---
+Stop paying for SaaS you can self-host.

-<p align="center">
-  Built with ❤️ by the <a href="https://thealtstack.com">AltStack Team</a>.
-</p>
+</div>