starred/tuxmate
1
0
Fork 0
mirror of https://github.com/abusoww/tuxmate.git synced 2026-04-17 19:53:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README

Browse Source
This commit is contained in:
N1C4T
2026-03-27 17:55:00 +04:00
parent 31dd15d43f
commit 8627dc0b69
1 changed files with 50 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@@ -12,44 +12,47 @@
</div> </div>
## 🐧 The only Mate you need for setup <div align="center">
<h2>🐧 The only Mate you need for setup</h2>
<p><strong>TuxMate is a cross-distro install command generator built for real Linux workflows.</strong></p>
<p>Choose apps once, generate inspectable commands/scripts for your distro, and run only what you understand.</p>
</div>
**TuxMate** is a simple web tool that generates install scripts for any Linux distro. Pick your apps, copy the command, done. > [!NOTE]
> Package mappings are verified against official distro registries and reviewed under strict contribution rules. Repositories evolve over time, so some entries can become outdated or unavailable later. If you spot an issue, please report it so we can fix it quickly.
Fresh install? New machine? Can't remember every package name? We've all been there. > [!WARNING]
> Security notice: TuxMate is a command generator (a wrapper around install logic), not a background installer. You copy and run commands yourself, so always inspect the generated command/script in the UI before executing. Downloadable scripts are produced with strict project rules, but no automation tool can replace user review. Confirm package names, flags, and targets for your distro before execution, and proceed at your own risk.
## 📦 Supported Package Managers
- Ubuntu / Debian (apt)
- Arch Linux (pacman + AUR)
- Fedora (dnf)
- openSUSE (zypper)
- Nix (declarative config)
- Flatpak
- Snap
- Homebrew (macOS + Linux)
## ✨ Features <div align="center">
### **Application Catalog** ## Supported Package Managers
180+ applications across 15 categories: browsers, communication, dev tools, terminals, media, creative software, gaming, office, VPN/network, security, and more.
### **Smart Script Generation** [Ubuntu (apt)](https://packages.ubuntu.com/) · [Debian (apt)](https://packages.debian.org/) · [Arch (pacman)](https://archlinux.org/packages/) · [AUR](https://aur.archlinux.org/) · [Fedora (dnf)](https://packages.fedoraproject.org/) · [openSUSE (zypper)](https://software.opensuse.org/) · [Nix (nixpkgs)](https://search.nixos.org/packages) · [Flatpak (Flathub)](https://flathub.org/) · [Snap (Snapcraft)](https://snapcraft.io/) · [Homebrew](https://formulae.brew.sh/)
- Detects already-installed packages
- Handles AUR packages automatically on Arch </div>
- **Nix Unfree Detection**: Warns compliant configuration for unfree packages (Discord, Spotify, etc.)
- Homebrew formula/cask separation for macOS ## Features
- Parallel installation for Flatpak
- Network retry with exponential backoff - Cross-distro generation: apt (Ubuntu/Debian), pacman + AUR helpers (yay/paru), dnf (Fedora), zypper (openSUSE), nix config output, Flatpak, Snap, and Homebrew.
- Progress bars with ETA - Native-first resolution with npm/script fallbacks only when a distro target is missing.
- Colored output and summary reports - Safe generation: inspectable output, installed-package checks, and retry with exponential backoff.
- Faster setup: parallel Flatpak installs.
- Homebrew-aware output with correct formula/cask separation.
- Clean terminal UX: colored logs, progress, ETA, and final summaries.
- Verification built in: AUR detection + allowlist, Nix unfree checks, and verified Flatpak/Snap badges.
- Productive UI: copy/download drawer, yay/paru switch, unfree warnings, and distro-aware context.
- Keyboard-first flow: Vim/arrow navigation, `/` search focus, and fast clear.
- PWA support with network-first service worker for resilient loading.
## 📸 Screenshots ## Screenshots
![1](src/screenshots/1.png) ![1](src/screenshots/1.png)
![2](src/screenshots/2.png) ![2](src/screenshots/2.png)
@@ -59,7 +62,7 @@ Fresh install? New machine? Can't remember every package name? We've all been th
<details> <details>
<summary><h2>💻 Development</h2></summary> <summary><h3>Development</h3></summary>
```bash ```bash
npm install npm install
@@ -79,89 +82,52 @@ npm start
<details> <details>
<summary><h2>🗂️ Project Structure</h2></summary> <summary><h3>Project Structure</h3></summary>
``` - `src/app/`: App Router entrypoints, layout, globals, and error boundary.
src/ - `src/components/`: UI modules (catalog, command drawer, distro selector, search, shared UI primitives).
├── app/ # Next.js app router - `src/hooks/`: App interaction hooks (state orchestration, keyboard navigation, theme, tooltips).
│ ├── page.tsx # Main page component - `src/lib/apps/`: Source-of-truth app registry (category JSON files).
│ ├── layout.tsx # Root layout with meta tags - `src/lib/scripts/`: Distro-specific script generators and shared shell helpers.
│ ├── globals.css # Tailwind styles - `src/lib/generateInstallScript.ts`: Main orchestration for native targets + universal fallbacks.
│ ├── error.tsx # Error boundary - `src/lib/verification.ts`: Verified source badges (Flathub/Snap).
│ └── favicon.ico # Site favicon - `src/__tests__/`: Unit tests for data, script behavior, and utilities.
├── 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/
│ ├── apps/ # JSON application files by category
│ ├── data.ts # Categories, distros, and app unifier
│ ├── aur.ts # AUR package detection
│ ├── analytics.ts # Umami tracking
│ ├── utils.ts # Utility functions
│ ├── generateInstallScript.ts
│ └── scripts/ # Per-distro script generators
└── __tests__/ # Vitest unit tests
```
</details> </details>
<details> <details>
<summary><h2>🐳 Docker Deployment</h2></summary> <summary><h3>Docker Deployment</h3></summary>
### Quick Start with Docker ### Build and Run
```bash ```bash
# Build the Docker image
docker build -t tuxmate:latest . docker build -t tuxmate:latest .
# Run the container
docker run -p 3000:3000 tuxmate:latest docker run -p 3000:3000 tuxmate:latest
``` ```
### Using Pre-built Images ### Use Prebuilt Image (GHCR)
Pre-built Docker images are automatically published to GitHub Container Registry:
```bash ```bash
# Pull and run the latest image
docker pull ghcr.io/abusoww/tuxmate:latest docker pull ghcr.io/abusoww/tuxmate:latest
docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:latest docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:latest
# Or use a specific version # Version pinning example
docker pull ghcr.io/abusoww/tuxmate:v1.0.0 docker pull ghcr.io/abusoww/tuxmate:v1.0.0
docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:v1.0.0 docker run -p 3000:3000 ghcr.io/abusoww/tuxmate:v1.0.0
``` ```
### Using Docker Compose (Recommended) ### Docker Compose
```bash ```bash
# Start the application
docker-compose up -d docker-compose up -d
# View logs
docker-compose logs -f docker-compose logs -f
# Stop the application
docker-compose down docker-compose down
``` ```
Open [http://localhost:3000](http://localhost:3000) Open [http://localhost:3000](http://localhost:3000)
### Configuration ### Port Mapping
The Docker container exposes port 3000 by default. You can customize the port mapping:
```bash ```bash
docker run -p 8080:3000 tuxmate:latest docker run -p 8080:3000 tuxmate:latest
@@ -169,14 +135,10 @@ docker run -p 8080:3000 tuxmate:latest
### Environment Variables ### Environment Variables
The following environment variables are configured by default:
- `NODE_ENV=production` - Run in production mode - `NODE_ENV=production` - Run in production mode
- `PORT=3000` - Application port - `PORT=3000` - Application port
- `NEXT_TELEMETRY_DISABLED=1` - Disable Next.js anonymous telemetry - `NEXT_TELEMETRY_DISABLED=1` - Disable Next.js anonymous telemetry
You can override these when running the container:
```bash ```bash
docker run -p 3000:3000 \ docker run -p 3000:3000 \
-e PORT=3000 \ -e PORT=3000 \
@@ -188,33 +150,14 @@ docker run -p 3000:3000 \
<details> <details>
<summary><h2>🛠️ Tech Stack</h2></summary> <summary><h3>Tech Stack</h3></summary>
- [Next.js](https://nextjs.org/) 16 (App Router) - Core: [Next.js](https://nextjs.org/) 16 (App Router), [React](https://react.dev/) 19, [TypeScript](https://www.typescriptlang.org/)
- [React](https://react.dev/) 19 - UI: [Tailwind CSS](https://tailwindcss.com/) 4, [Framer Motion](https://www.framer.com/motion/), [GSAP](https://gsap.com/), [Lucide React](https://lucide.dev/)
- [TypeScript](https://www.typescriptlang.org/) - Testing: [Vitest](https://vitest.dev/)
- [Tailwind CSS](https://tailwindcss.com/) 4
- [Framer Motion](https://www.framer.com/motion/)
- [GSAP](https://gsap.com/)
- [Vitest](https://vitest.dev/) (testing)
- [Lucide React](https://lucide.dev/) (icons)
</details> </details>
### ⌨️ 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 ## 🤝 Contribution
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
@@ -258,7 +201,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
<details> <details>
<summary><h4>🔗 Related Projects</h4></summary> <summary><h4>Related Projects</h4></summary>
- **[LinuxToys](https://github.com/psygreg/linuxtoys)** – User-friendly collection of tools for Linux with an intuitive interface - **[LinuxToys](https://github.com/psygreg/linuxtoys)** – User-friendly collection of tools for Linux with an intuitive interface
- **[Nixite](https://github.com/aspizu/nixite)** – Generates bash scripts to install Linux software, inspired by Ninite - **[Nixite](https://github.com/aspizu/nixite)** – Generates bash scripts to install Linux software, inspired by Ninite
@@ -268,7 +211,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
<details> <details>
<summary><h4>💳 Monetary Contributions</h4></summary> <summary><h4>Monetary Contributions</h4></summary>
No tips jar here. I’m happy just knowing you’re using Linux. No tips jar here. I’m happy just knowing you’re using Linux.