A personal collection of Bash scripts for Debian-based x86_64 systems. Designed for server bootstrapping, monitoring stack deployment, web server setup, shell quality-of-life tweaks, media downloads, and day-to-day automation.

Table of Contents

• Features
• Compatibility
• Scripts Overview
• Repository Structure
• Detailed Descriptions
• Quick Start
• Important Notes
• Requirements
• Contributing
• License

Features

• Colored output with clear progress indicators and status messages
• Interactive prompts with safety confirmations before destructive actions
• Idempotent design — safe to re-run without breaking existing configs
• Automatic backups of configuration files before modification
• Comprehensive logging with final run summaries
• Security-focused defaults where the script scope allows it

Compatibility

• Platform: Debian-based GNU/Linux distributions
• Architecture: x86_64 / amd64

Most scripts are architecture-neutral (apt, Docker, Python); The exception is download-java.sh, which hardcodes x64 in the Adoptium API URL and will fail on ARM.

• Shell: Bash 5.0+

Scripts Overview

Script	Purpose	Root	Idempotent
server-bootstrap.sh	Initial server setup, users, firewall, Fail2Ban	✅	✅
server-report.sh	Full system inventory report + archive	✅	✅
deploy-nginx.sh	Production Nginx + optional PHP-FPM, Grafana & Portainer proxy	✅	✅
deploy-grafana.sh	Grafana + Prometheus + Node Exporter via Docker	✅	✅
deploy-portainer.sh	Portainer CE container management UI via Docker	✅	✅
update-stacks.sh	Pull and redeploy all Docker Compose stacks under /opt/*	✅	✅
deploy-server.sh	Full-stack orchestrator: bootstrap → nginx → grafana → portainer from a single .env	✅	❌
setup-dev.sh	Install a full C++/Python/PHP/Node dev environment + LSP servers in one step	✅	✅
setup-flatpak.sh	Install Flatpak + Flathub + Discord, Steam, Telegram in one step	❌	✅
setup-pipx.sh	Install yt-dlp, gallery-dl, spotdl via pipx in one step	❌	✅
system-cleanup.sh	Clean up APT cache, old kernels, logs, temp files & Docker leftovers	✅	✅
browser-cleanup.sh	Clear cache, cookies, and history for Firefox, Chrome, Chromium, and others	❌	✅
set-bashrc-default.sh	Reset ~/.bashrc to the distribution default	❌	✅
create-swap-file.sh	Create and activate a swap file of any size	✅	✅
grant-sudo.sh	Add a user to the sudo group	✅	✅
ufw-firewalld-migration.sh	Remove UFW and replace it with Firewalld	✅	⚠️
install-virtualbox-guest-additions.sh	Install VirtualBox Guest Additions from apt	✅	✅
chmod-add-x.sh	Recursively add execute permission to .sh files in a path	❌	✅
chmod-remove-x.sh	Recursively remove execute permission from .sh files in a path	❌	✅
prompt-cli.sh	Gemini-based CLI assistant with markdown rendering; exposed as ask	❌	✅
git-clone-all.sh	Clone all public repositories from a GitHub user/profile	❌	✅
download-java.sh	Eclipse Temurin JDK/JRE installer (v8, 17, 21, 25)	✅	⚠️
discord-attachments-dl.sh	Download attachments from a Discord data export	❌	✅
yt-dlp-best-format.sh	Download best quality video as MP4 via yt-dlp	❌	✅
yt-dlp-audio-only.sh	Download audio only as MP3 via yt-dlp	❌	✅
yt-dlp-all-formats.sh	Download every resolution tier (480p–8K) via yt-dlp	❌	✅
bash-qol.sh	Install shell quality-of-life tools and configure Bash	✅	✅
oh-my-bash.sh	Install oh-my-bash with interactive theme selection	✅	✅
bash-qol-demo.sh	Demo for the Bash QOL terminal styling	❌	✅
git-fetch.sh	Fastfetch-style terminal portfolio card with live GitHub stats	❌	✅

⚠️ — mostly safe to re-run, but with caveats described in the script's section below.

Repository Structure

shell-toolkit/
├── server/                          # Server deployment, monitoring, and maintenance
│   ├── server-bootstrap.sh
│   ├── server-report.sh
│   ├── deploy-nginx.sh
│   ├── deploy-grafana.sh
│   ├── deploy-portainer.sh
│   └── update-stacks.sh
├── workflows/                       # Multi-step orchestrators and their config
│   ├── deploy-server/
│   │   ├── deploy-server.sh
│   │   └── .env.example
│   ├── setup-dev/
│   │   └── setup-dev.sh
│   ├── setup-flatpak/
│   │   └── setup-flatpak.sh
│   └── setup-pipx/
│       └── setup-pipx.sh
├── maintenance/                     # System utilities and one-off admin tasks
│   ├── system-cleanup.sh
│   ├── browser-cleanup.sh
│   ├── set-bashrc-default.sh
│   ├── create-swap-file.sh
│   ├── grant-sudo.sh
│   ├── ufw-firewalld-migration.sh
│   ├── install-virtualbox-guest-additions.sh
│   ├── chmod-add-x.sh
│   └── chmod-remove-x.sh
├── apt/                             # Individual apt package installers
│   ├── install-cpp.sh
│   ├── install-python.sh
│   ├── install-php.sh
│   ├── install-npm.sh
│   ├── install-docker.sh
│   ├── install-kdevelop.sh
│   ├── install-ghostwriter.sh
│   ├── install-okular.sh
│   ├── install-pipx.sh
│   ├── install-kio-admin.sh
│   ├── install-protonvpn.sh
│   ├── install-tor-browser.sh
│   ├── install-veracrypt.sh
│   └── install-virtualbox.sh
├── flatpak/                         # Flatpak app installers
│   ├── install-flatpak.sh
│   ├── install-discord.sh
│   ├── install-steam.sh
│   └── install-telegram.sh
├── pipx/                            # pipx-based tool installers
│   ├── install-yt-dlp.sh
│   ├── install-gallery-dl.sh
│   └── install-spotdl.sh
├── lsp/                             # Language server installations
│   ├── install-bash-language-server.sh
│   └── install-markdown-language-server.sh
├── utilities/                       # General-purpose standalone tools
│   ├── prompt-cli.sh
│   ├── git-clone-all.sh
│   ├── download-java.sh
│   └── discord-attachments-dl.sh
├── yt-dlp/                          # Video and audio download helpers
│   ├── yt-dlp-best-format.sh
│   ├── yt-dlp-audio-only.sh
│   └── yt-dlp-all-formats.sh
├── qol/                             # Bash quality-of-life and terminal customization
│   ├── bash-qol.sh
│   ├── oh-my-bash.sh
│   └── bash-qol-demo.sh
├── showcase/                        # Terminal portfolio and visual scripts
│   └── git-fetch.sh
├── README.md
└── LICENSE

Detailed Descriptions

---

server/ — deployment, monitoring, bootstrapping

server-bootstrap.sh — initial server hardening and configuration

Initial hardening and configuration for a fresh server.

• Installs essential admin tools such as htop, ranger, git, curl, wget, and more
• Offers optional hardware diagnostic utilities
• Creates and configures a sudo-enabled user account
• Sets up Firewalld with sensible default rules
• Configures Fail2Ban for SSH brute-force protection
• Prints a full system summary at the end

server-report.sh — full system inventory report + archive

Generates a comprehensive server inventory report, saved locally and archived.

• Collects hardware specs, OS info, network interfaces, active users, running services, Docker containers, Nginx config, and firewall rules
• Saves all data to ~/server-report/
• Packages everything into server-report.tar.gz for easy transfer
• Displays a color-coded console summary with key metrics

deploy-nginx.sh — production Nginx + optional PHP-FPM, Grafana & Portainer proxy

Deploys a hardened, production-ready Nginx web server.

• Installs Nginx with optional PHP-FPM integration
• Generates a clean virtual host with security headers and other baseline best practices
• Optionally installs avahi-daemon for mDNS / .local hostname resolution on the LAN
• Can add reverse proxies for Grafana at /grafana and Portainer at /portainer
• Configures Firewalld for HTTP, HTTPS, and mDNS
• Creates a clean default index.html

deploy-grafana.sh — Grafana + Prometheus + Node Exporter via Docker

Deploys a full observability stack: Grafana + Prometheus + Node Exporter.

• Managed via Docker Compose
• Uses a dedicated secret for the Grafana admin password
• Pre-configures Prometheus to scrape Node Exporter metrics
• Attempts to auto-import the Node Exporter Full dashboard (ID 19937)
• Persists data under /opt/grafana-stack/

Default binding: 127.0.0.1:3000 — use deploy-nginx.sh to expose it externally.

deploy-portainer.sh — Portainer CE container management UI via Docker

Deploys Portainer CE — a lightweight web UI for managing Docker containers.

• Managed via Docker Compose
• Uses a dedicated secret for the Portainer admin password
• Stores data under /opt/portainer-stack/

Default binding: 127.0.0.1:9000 — use deploy-nginx.sh to expose it externally.

update-stacks.sh — pull and redeploy all Docker Compose stacks under /opt/*

Updates and redeploys every Docker Compose stack found under /opt/*.

• Lists currently running containers before starting
• Detects docker-compose.yml, compose.yml, compose.yaml, and docker-compose.yaml
• Runs docker compose pull followed by docker compose up -d for each stack
• Detects whether new images were actually pulled
• Skips directories with no compose file or where the pull fails
• Prints a final summary of updated, unchanged, and skipped stacks

---

workflows/ — multi-step orchestrators

deploy-server.sh — full-stack orchestrator from a single .env

Orchestrates a full server deployment by running four scripts in sequence from a single .env config file.

• Validates all .env variables before starting — fails fast with clear errors
• Pipes answers to each subscript via printf, safely handling special characters in credentials
• Handles sudo user creation between the bootstrap and Nginx steps
• Prints a deployment plan before running and confirms before proceeding
• Located in workflows/deploy-server/ alongside its .env.example config template

Designed for fresh deployments only — re-running on an existing system breaks prompt ordering in the subscripts.

setup-dev.sh — full dev environment in one step

Installs a complete development environment by chaining scripts from apt/ and lsp/.

• Runs in order: install-cpp.sh, install-python.sh, install-php.sh, install-kdevelop.sh, install-npm.sh, install-ghostwriter.sh, install-docker.sh
• Then installs install-bash-language-server.sh and install-markdown-language-server.sh
• Each subscript is executed individually so a failure is isolated and traceable
• Located in workflows/setup-dev/

setup-flatpak.sh — Flatpak + standard GUI apps in one step

Installs Flatpak and a standard set of GUI applications in one step.

• Runs in order: install-flatpak.sh (Flatpak + Flathub), install-telegram.sh, install-discord.sh, install-steam.sh
• Located in workflows/setup-flatpak/

setup-pipx.sh — Python CLI tools via pipx in one step

Installs a curated set of Python CLI tools via pipx in one step.

• Runs in order: install-gallery-dl.sh, install-yt-dlp.sh, install-spotdl.sh
• Located in workflows/setup-pipx/

---

maintenance/ — system utilities and one-off admin tasks

system-cleanup.sh — free up disk space

Frees up disk space by clearing caches, logs, and other safe-to-remove files.

• Runs apt-get autoremove, autoclean, and clean
• Detects and optionally removes old kernel packages while keeping the running kernel
• Vacuums journald logs and removes rotated/compressed logs in /var/log older than 7 days
• Clears stale files from /tmp and /var/tmp
• Optionally prunes Docker images, containers, networks, and volumes with separate confirmations
• Clears thumbnail caches for all home directories
• Prints a summary of freed disk space at the end

browser-cleanup.sh — clear cache, cookies, and history for major browsers

Clears browser data for Firefox, Chrome, Chromium, Brave, Edge, Opera, and Vivaldi.

• Stops all detected browser processes before cleaning
• Removes cookies, history, cache, session data, and local storage per browser
• Only cleans browsers that are actually installed on the system
• No root required — operates entirely within the current user's home directory

set-bashrc-default.sh — reset ~/.bashrc to the distro default

Restores ~/.bashrc to the distro default.

• Backs up the current ~/.bashrc with a timestamp before overwriting
• Restores the file from /etc/skel/.bashrc
• Requires explicit confirmation before making changes

create-swap-file.sh — create and activate a swap file

Creates and activates a swap file at /swapfile.

• Usage: ./create-swap-file.sh <size> (e.g. 4G, 8192M, 2GiB)
• Accepts G, GB, GiB, M, MB, MiB, T, TB, TiB units
• Detects and safely handles an existing swap file with a confirmation prompt
• Enables the new swap immediately and persists it via /etc/fstab

grant-sudo.sh — add a user to the sudo group

Adds an existing user to the sudo group.

• Usage: ./grant-sudo.sh <username> or run as sudo (inherits SUDO_USER automatically)
• Validates that the target user exists and is not root

ufw-firewalld-migration.sh — replace UFW with Firewalld

Replaces UFW with Firewalld on Debian/Ubuntu systems.

• Disables and removes UFW
• Installs Firewalld and enables it on boot
• Opens SSH in the default zone before finishing so the session is not dropped

⚠️ Idempotency caveat: safe to run on a system that still has UFW, but a no-op if UFW is already gone and Firewalld is already running — it will not reconfigure an existing Firewalld setup.

install-virtualbox-guest-additions.sh — install VirtualBox Guest Additions from apt

Installs VirtualBox Guest Additions from the distribution's apt repository.

• Supports Debian, Ubuntu, Linux Mint, Pop!_OS, and Kali
• Installs virtualbox-guest-x11 and virtualbox-guest-utils
• Reminds the user to reboot to activate the additions

chmod-add-x.sh / chmod-remove-x.sh — bulk permission toggle for .sh files

Recursively add or remove the execute bit on all .sh files under a given path.

• Usage: ./chmod-add-x.sh <path> / ./chmod-remove-x.sh <path>
• No root required unless the target path requires elevated access

---

apt/ — individual package installers (14 scripts)

Individual apt-based package installers. Each script is self-contained, idempotent, and requires root.

Script	What it installs
install-cpp.sh	build-essential, gcc, g++, clang, cmake, ninja-build, gdb, lldb
install-python.sh	python3, python3-pip, python3-venv
install-php.sh	php, php-cli, php-fpm, common PHP extensions
install-npm.sh	nodejs, npm
install-docker.sh	Docker Engine (docker.io), Docker Compose plugin; enables and starts the service
install-kdevelop.sh	KDevelop IDE
install-ghostwriter.sh	Ghostwriter Markdown editor
install-okular.sh	Okular document viewer
install-pipx.sh	pipx and ensures ~/.local/bin is on PATH
install-kio-admin.sh	kio-admin for Dolphin root access
install-protonvpn.sh	ProtonVPN CLI from the official Proton apt repository
install-tor-browser.sh	Tor Browser via the official Tor Project apt repository
install-veracrypt.sh	VeraCrypt from the official PPA
install-virtualbox.sh	VirtualBox from the official Oracle apt repository

---

flatpak/ — Flatpak app installers (4 scripts)

Flatpak-based app installers. Each script is idempotent and does not require root (except install-flatpak.sh).

Script	What it installs
install-flatpak.sh	flatpak, adds the Flathub remote, optionally enables KDE Discover integration
install-discord.sh	Discord from Flathub
install-steam.sh	Steam from Flathub
install-telegram.sh	Telegram Desktop from Flathub

---

pipx/ — Python CLI tool installers (3 scripts)

pipx-based CLI tool installers. Each script is idempotent and does not require root.

Script	What it installs
install-yt-dlp.sh	yt-dlp
install-gallery-dl.sh	gallery-dl
install-spotdl.sh	spotdl

---

lsp/ — language server installations (2 scripts)

Language server installations for editor/IDE LSP integration via npm. Both scripts are idempotent — they use marker blocks in ~/.bashrc and skip installation if the server is already present.

Script	What it installs
install-bash-language-server.sh	bash-language-server via npm into ~/.local/npm; adds to ~/.bashrc
install-markdown-language-server.sh	markdown-language-server via npm into ~/.local/npm; adds to ~/.bashrc

---

utilities/ — general-purpose standalone tools

prompt-cli.sh — Gemini-based CLI assistant exposed as ask

A terminal-based assistant client for the Google Gemini API with markdown rendering.

• Usage: ask [--model NAME] <prompt text>
• Self-installs into ~/.local/bin/ on first run
• Stores the API key in ~/.config/prompt-cli/keys.env
• Renders markdown directly in the terminal
• Includes --setup, --reset, --uninstall, and --help
• Uses the ask command name because prompt is already taken by oh-my-bash

git-clone-all.sh — clone all public repos from a GitHub user

Clones every public repository belonging to a GitHub user or organization.

• Usage: ./git-clone-all.sh <github-username-or-url> [target-dir]
• Accepts either a bare username or a full github.com/<user> URL
• Paginates through the GitHub API to fetch all repositories
• Clones each repo into the target directory (default ./repos)
• Skips repositories that are already cloned locally
• No root required

download-java.sh — Eclipse Temurin JDK/JRE installer

Downloads and installs multiple Eclipse Temurin (Adoptium) JDK/JRE builds.

• Supported versions: 8, 17, 21, 25
• Downloads both JDK and JRE for each version
• Installs to /opt/java/temurin/
• Updates shell configuration so the installed Java versions can be used easily

⚠️ Idempotency caveat: hardcodes x64 in the Adoptium API URL — will fail on ARM. Re-running will re-download and overwrite existing installations without prompting.

discord-attachments-dl.sh — download attachments from a Discord data export

Downloads media attachments from a local Discord data export.

• Scans all c*/ channel folders inside the export directory
• Parses messages.json using jq to extract attachment URLs
• Downloads files to an attachments/ subdirectory per channel
• Skips already-downloaded files
• Logs failed downloads for review

---

yt-dlp/ — video and audio download helpers (3 scripts)

All three scripts share the same conventions: they install jq and wget if missing, use Firefox cookies and a Node.js JS runtime for restricted videos, and retry up to 100 times with randomized sleep intervals. Output filenames always include uploader, upload date, title, and video ID. No root required.

yt-dlp-best-format.sh — best quality video as MP4

• Usage: ./yt-dlp-best-format.sh <URL> [extra yt-dlp options]
• Prefers bestvideo[ext=mp4]+bestaudio[ext=m4a], falling back to the best overall format

yt-dlp-audio-only.sh — audio only as MP3

• Usage: ./yt-dlp-audio-only.sh <URL> [extra yt-dlp options]
• Extracts audio at the best available quality (--audio-quality 0) and converts to MP3

yt-dlp-all-formats.sh — every resolution tier up to 8K

• Usage: ./yt-dlp-all-formats.sh <URL> [extra yt-dlp options]
• Targets 480p, 720p, 1080p, 1440p, 2160p (4K), and 4320p (8K) with bestaudio[ext=m4a]
• Falls back to best[ext=mp4] / best if no matching tier is available
• Output filename also includes the resolution

---

qol/ — Bash quality-of-life and terminal customization

bash-qol.sh — install shell tools and configure Bash

Installs shell quality-of-life tools and configures the current user's Bash environment.

• Installs fzf, zoxide, ripgrep, bat, eza, and bash-completion
• Adds the official eza apt repository when the package is not available in distro repos
• Updates ~/.bashrc and ~/.inputrc with a managed block
• Adds aliases, completion tweaks, and history improvements
• Designed to be re-run safely

oh-my-bash.sh — install oh-my-bash with interactive theme selection

Installs oh-my-bash and lets the user pick a theme via an interactive preview.

• Uses theme screenshots rendered in the terminal with chafa
• Supports both upstream installation and a manual integration mode
• Preserves existing Bash customizations in manual mode
• Updates only the managed block when re-run
• Requires git and chafa

bash-qol-demo.sh — standalone demo of the Bash QOL terminal styling

A standalone demonstration of the Bash QOL terminal styling.

• Creates a temporary sandbox with sample files
• Shows off formatted output and terminal UI behavior
• Useful as a preview before committing to bash-qol.sh
• No root required

---

showcase/ — terminal portfolio and visual scripts

git-fetch.sh — fastfetch-style terminal portfolio card with live GitHub stats

A fastfetch-style terminal portfolio card with live GitHub stats, rendered in 24-bit ANSI color.

• Displays identity, role, focus, and tech stack as Nerd Fonts pill badges
• Fetches live data from the GitHub API: repo count, total stars, forks, followers, last push date
• Computes top languages by byte count across all public repos and shows them with percentage and icon
• Uses a dot spinner while API requests are in flight
• Displays a 16-color palette at the bottom using the project's brand colors
• Requires Nerd Fonts to render the pill badge glyphs correctly

---

Quick Start

1. Clone the repository and enter the project directory:

git clone https://github.com/VargKernel/shell-toolkit.git
cd shell-toolkit

2. Make all scripts executable:

find . -type f -name "*.sh" -exec chmod +x {} \;

3. Choose how to proceed:

Option A — run scripts individually in logical order for a fresh server setup:

# 1. Harden and configure the new server
sudo ./server/server-bootstrap.sh

# 2. Generate a full system inventory
sudo ./server/server-report.sh

# 3. Deploy Nginx (optionally with PHP-FPM, Grafana & Portainer proxy)
sudo ./server/deploy-nginx.sh

# 4. Deploy the monitoring stack (requires Docker)
sudo ./server/deploy-grafana.sh

# 5. Deploy Portainer CE for container management (requires Docker)
sudo ./server/deploy-portainer.sh

# 6. Periodically free up disk space
sudo ./maintenance/system-cleanup.sh

# 7. Periodically pull and redeploy updated Docker stacks
sudo ./server/update-stacks.sh

Option B — deploy the full server stack in one step using the orchestrator:

cd workflows/deploy-server
cp .env.example .env
nano .env
sudo ./deploy-server.sh

Option C — set up a development workstation:

# Full dev environment (C++, Python, PHP, Node, Docker, KDevelop, LSP servers)
sudo ./workflows/setup-dev/setup-dev.sh

# Flatpak apps (Telegram, Discord, Steam)
./workflows/setup-flatpak/setup-flatpak.sh

# Python CLI tools via pipx (yt-dlp, gallery-dl, spotdl)
./workflows/setup-pipx/setup-pipx.sh

# Shell quality-of-life tools (fzf, zoxide, eza, bat, ripgrep)
sudo ./qol/bash-qol.sh

Each script is self-contained and can be run independently at any time.

Important Notes

Warning

Most scripts require root or sudo privileges and make real system changes. Always review the script source before running on a production machine.

Important

Grafana is bound to 127.0.0.1:3000 by default. Portainer is bound to 127.0.0.1:9000 by default. Use deploy-nginx.sh to create reverse proxies for external access. Change default admin passwords immediately after first login.

Note

deploy-server.sh is designed for fresh deployments only — re-running it on an existing setup will break prompt ordering in the subscripts. prompt-cli.sh stores the Gemini API key locally in ~/.config/prompt-cli/keys.env. bash-qol.sh and oh-my-bash.sh modify shell startup files such as ~/.bashrc. git-fetch.sh requires Nerd Fonts to render correctly.

Tip

Scripts are idempotent where possible, but a dry-run review (bash -n script.sh) before first execution is always a good idea.

Requirements

• Debian-based x86_64 Linux system
• bash 5.0+
• Root or sudo access for system-level scripts
• Internet connection for package and Docker image downloads
• docker + docker compose (only for deploy-grafana.sh, deploy-portainer.sh, update-stacks.sh, and deploy-server.sh)
• jq (only for discord-attachments-dl.sh, prompt-cli.sh, and the yt-dlp-* scripts)
• yt-dlp and a Firefox profile with cookies (only for the yt-dlp-* scripts)
• pipx (only for scripts in pipx/ and the setup-pipx workflow)
• flatpak (only for scripts in flatpak/ and the setup-flatpak workflow)
• npm (only for scripts in lsp/)
• A Google Gemini API key (only for prompt-cli.sh)
• Nerd Fonts (only for git-fetch.sh)

Contributing

Issues and Pull Requests are welcome. If a script fits the collection's scope (server ops, monitoring, deployment, shell tooling, or useful automation), feel free to open a PR.

Please follow the existing code style: colored output, safety prompts, and inline English comments.

License

Distributed under the GNU General Public License v3.0.

Built for self-hosted infrastructure, automation, and observability.