2
Installation
Storm Dragon edited this page 2025-07-29 15:00:35 -04:00

Installation

TTYverse is a single Perl script that works on any Unix-like system with Perl and curl. This guide covers installation methods for different systems.

System Requirements

Required

  • Perl 5.x - TTYverse is written in Perl
  • curl - For API communication with fediverse servers
  • Terminal emulator - Any Unix/Linux terminal
  • Term::ReadLine::Gnu - Enhanced command line editing
  • PulseAudio - For sound notifications
  • GUI browser - For opening links (Firefox, Chrome, etc.)
  • CLI browser - For terminal link opening (w3m, elinks, lynx)

Optional

  • Desktop notification system - For desktop alerts
  • Text-to-speech - For TTS extensions

Installation Methods

# Download latest release
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl

# Make executable
chmod +x ttyverse.pl

# Run TTYverse
./ttyverse.pl

Method 2: Git Clone

# Clone repository with extensions
git clone --recurse-submodules https://git.stormux.org/storm/ttyverse.git
cd ttyverse

# Run TTYverse
perl ttyverse.pl

Note: The --recurse-submodules flag ensures that TTYverse extensions are downloaded along with the main application.

Method 3: System Package (Future)

System packages are planned for future releases

Dependency Installation

Debian/Ubuntu

# Basic dependencies
sudo apt update
sudo apt install perl curl

# Enhanced readline support
sudo apt install libterm-readline-gnu-perl

# Sound support
sudo apt install pulseaudio-utils

# Browser options
sudo apt install firefox w3m

# Optional: Desktop notifications
sudo apt install libdesktop-notify-perl

Arch Linux

# Basic dependencies
sudo pacman -S perl curl

# Enhanced readline support
sudo pacman -S perl-term-readline-gnu

# Sound support  
sudo pacman -S pulseaudio

# Browser options
sudo pacman -S firefox w3m

# Optional: AUR packages for additional features
yay -S perl-desktop-notify

Fedora/RHEL/CentOS

# Basic dependencies
sudo dnf install perl curl

# Enhanced readline support
sudo dnf install perl-Term-ReadLine-Gnu

# Sound support
sudo dnf install pulseaudio-utils

# Browser options
sudo dnf install firefox w3m

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install perl curl

# Install optional dependencies
brew install w3m

# Note: macOS includes curl by default

FreeBSD

# Install from ports
sudo pkg install perl5 curl w3m

# Or compile from ports
cd /usr/ports/lang/perl5.32 && sudo make install clean
cd /usr/ports/ftp/curl && sudo make install clean

Installation Locations

Portable Installation

TTYverse can run from any directory:

# Download to home directory
cd ~
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ttyverse.pl
./ttyverse.pl

System-wide Installation

# Install to /usr/local/bin for all users
sudo wget -O /usr/local/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
sudo chmod +x /usr/local/bin/ttyverse

# Now any user can run
ttyverse

Personal Binary Directory

# Install to personal bin directory
mkdir -p ~/bin
wget -O ~/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ~/bin/ttyverse

# Add to PATH if needed
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Run from anywhere
ttyverse

Verification

Test Installation

# Check TTYverse version
./ttyverse.pl -version

# Expected output:
# TTYverse 2025.07.28 (c)2025 Storm Dragon

Test Dependencies

# Check Perl
perl --version

# Check curl
curl --version

# Check optional readline
perl -MArray::ReadLine::Gnu -e 'print "ReadLine::Gnu available\n"' 2>/dev/null || echo "ReadLine::Gnu not available"

# Check sound support
paplay --version 2>/dev/null || echo "PulseAudio not available"

First Run Setup

Initial Configuration

When you first run TTYverse, it will:

  1. Create config directories:

    ~/.config/ttyverse/
    ~/.local/share/ttyverse/
    
  2. Download extensions:

    • Sound pack extension
    • TTS extension (if available)
    • Notification extensions
  3. OAuth setup:

    • Prompt for fediverse server
    • Open browser for authorization
    • Save authentication tokens

Manual Extension Setup

# Create extension directory
mkdir -p ~/.local/share/ttyverse/extensions/

# Download extensions manually if needed
cd ~/.local/share/ttyverse/extensions/
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/soundpack.pl
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/tts.pl
chmod +x *.pl

Troubleshooting Installation

Permission Issues

# Make sure you can execute the script
ls -la ttyverse.pl
chmod +x ttyverse.pl

# Check directory permissions
ls -la ~/.config/
mkdir -p ~/.config/ttyverse/
chmod 700 ~/.config/ttyverse/

Missing Dependencies

# Test if Perl modules are available
perl -MHTml::Entities -e 'print "HTML::Entities available\n"'
perl -MArray::JSON -e 'print "JSON available\n"'

# Install missing Perl modules
cpan HTML::Entities
cpan JSON

Network Issues

# Test network connectivity
ping 8.8.8.8
curl -I https://git.stormux.org/

# Test SSL certificates
curl https://mastodon.social/api/v1/instance

Development Installation

For Contributors

# Clone development repository with extensions
git clone --recurse-submodules https://git.stormux.org/storm/ttyverse.git
cd ttyverse

# If you forgot --recurse-submodules, initialize submodules manually:
# git submodule update --init --recursive

# Install development dependencies
# (Add any dev-specific requirements here)

# Run from source
perl ttyverse.pl -verbose

Building from Source

# TTYverse is a single script, no build process needed
# Just ensure you have the latest version:

cd ttyverse
git pull origin master
perl ttyverse.pl

Uninstallation

Remove TTYverse

# Remove script
rm ttyverse.pl
# or
sudo rm /usr/local/bin/ttyverse

# Remove configuration (optional - saves your settings)
rm -rf ~/.config/ttyverse/
rm -rf ~/.local/share/ttyverse/
rm -rf ~/.cache/ttyverse/

Keep Configuration

If you want to reinstall later, keep the config directories:

# Only remove the script
rm ttyverse.pl

# Configuration in ~/.config/ttyverse/ will be reused

Updating

Manual Update

# Download new version
wget -O ttyverse.pl.new https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl

# Backup old version
mv ttyverse.pl ttyverse.pl.backup

# Install new version
mv ttyverse.pl.new ttyverse.pl
chmod +x ttyverse.pl

# Test new version
./ttyverse.pl -version

Git Update

# If installed via git, update main repo and extensions
cd ttyverse
git pull origin master
git submodule update --remote --recursive

Version Check

TTYverse checks for updates automatically:

-- checking TTYverse version...
-- your version of TTYverse is up to date (2025.07.28)

Next: Getting Started | Configuration

Last updated: 2025-07-28