tuxmate/README.md

🐧 The only Mate you need for setup

TuxMate is a web-based Linux application installer that generates distro-specific shell scripts, that aims to be the simplest way to bulk-install applications on a fresh Linux system.

Maybe you've just installed a fresh Linux distro. Perhaps you're setting up a new machine or can't remember all the package names for your favorite apps?

📦 Supported Package Managers

• Ubuntu / Debian (apt)
• Arch Linux (pacman + AUR)
• Fedora (dnf)
• openSUSE (zypper)
• Nix (nix-env)
• Flatpak
• Snap
• Homebrew (macOS + Linux)

✨ Features 🌟

Application Catalog

180+ applications across 15 categories: browsers, communication, dev tools, terminals, media, creative software, gaming, office, VPN/network, security, and more.

Smart Script Generation

• Detects already-installed packages
• Handles AUR packages automatically on Arch
• Homebrew formula/cask separation for macOS
• Parallel installation for Flatpak
• Network retry with exponential backoff
• Progress bars with ETA
• Colored output and summary reports

📸 Screenshots

💻 Development

npm install
npm run dev

Open http://localhost:3000

Build

npm run build
npm start

🗂️ Project Structure

src/
├── app/                    # Next.js app router
│   ├── page.tsx            # Main page component
│   ├── layout.tsx          # Root layout with meta tags
│   ├── globals.css         # Tailwind styles
│   ├── error.tsx           # Error boundary
│   └── favicon.ico         # Site favicon
├── components/
│   ├── app/                # App cards & categories
│   ├── command/            # Command footer & AUR settings
│   ├── common/             # Tooltips, loading states
│   ├── distro/             # Distribution selector
│   ├── header/             # Header links & info
│   ├── search/             # Search overlay
│   └── ui/                 # Theme toggle
├── hooks/                  # React hooks
│   ├── useLinuxInit.ts     # Main app state management
│   ├── useKeyboardNavigation.ts
│   ├── useTheme.tsx
│   ├── useTooltip.ts
│   └── useDelayedTooltip.ts
├── lib/
│   ├── data.ts             # Apps, distros, icons
│   ├── aur.ts              # AUR package detection
│   ├── analytics.ts        # Umami tracking
│   ├── utils.ts            # Utility functions
│   ├── generateInstallScript.ts
│   └── scripts/            # Per-distro script generators
└── __tests__/              # Vitest unit tests

🐳 Docker Deployment

Quick Start with Docker

# Build the Docker image
docker build -t tuxmate:latest .

# Run the container
docker run -p 3000:3000 tuxmate:latest

Using Pre-built Images

Pre-built Docker images are automatically published to GitHub Container Registry:

# Pull and run the latest image
docker pull ghcr.io/abusoww/tuxmate:latest
docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:latest

# Or use a specific version
docker pull ghcr.io/abusoww/tuxmate:v1.0.0
docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:v1.0.0

Using Docker Compose (Recommended)

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

Open http://localhost:3000

Configuration

The Docker container exposes port 3000 by default. You can customize the port mapping:

docker run -p 8080:3000 tuxmate:latest

Environment Variables

The following environment variables are configured by default:

• NODE_ENV=production - Run in production mode
• PORT=3000 - Application port
• NEXT_TELEMETRY_DISABLED=1 - Disable Next.js anonymous telemetry

You can override these when running the container:

docker run -p 3000:3000 \
  -e PORT=3000 \
  -e NEXT_TELEMETRY_DISABLED=1 \
  tuxmate:latest

🛠️ Tech Stack

• Next.js 16 (App Router)
• React 19
• TypeScript
• Tailwind CSS 4
• Framer Motion
• GSAP
• Vitest (testing)
• Lucide React (icons)

⌨️ Keyboard Shortcuts

Key	Action
↑ ↓ ← → / h j k l	Navigate apps
Space	Toggle app selection
Esc	Clear focus
/	Focus search
y	Copy command
d	Download script
t	Toggle theme
c	Clear all selections
Tab	Toggle preview drawer

🤝 Contribution

See CONTRIBUTING.md for contribution guidelines.

🎯 Roadmap

Completed

• Multi-distro support (Ubuntu, Debian, Arch, Fedora, openSUSE)
• Nix, Flatpak & Snap universal package support
• 180+ applications across 15 categories
• Smart script generation with error handling
• Dark / Light theme toggle with smooth animations
• Copy command & Download script
• Custom domain
• Docker support
• CI/CD shortcuts & workflow
• Search & filter applications (Real-time)
• AUR Helper selection (yay/paru) + Auto-detection
• Keyboard navigation (Vim keys, Arrows, Space, Esc, Enter)
• Package availability indicators (including AUR badges)
• Homebrew support (macOS + Linux)

Planned

• Winget support (Windows)
• Save custom presets / profiles
• Share configurations via URL
• More distros (Gentoo, Void, Alpine)
• PWA support for offline use
• Companion CLI tool
• Expand application catalog (200+)
• Dotfiles integration

🔗 Related Projects

• LinuxToys – User-friendly collection of tools for Linux with an intuitive interface
• Nixite – Generates bash scripts to install Linux software, inspired by Ninite
• tuxmate-cli – CLI companion for tuxmate, uses tuxmate's package database

💳 Monetary Contributions

No tips jar here. I’m happy just knowing you’re using Linux.

If you want to earn some real life karma points, consider donating to the following organizations:

• KDE e.V.
• Gnome Foundation
• Arch Linux
• The Tor Project

Comments, suggestions, bug reports and contributions are welcome.

📜 License

Licensed under the GPL-3.0 License
Free software — you can redistribute and modify it under the terms of the GNU General Public License.