Skip to content

INSTALL.md

Latest commit

 

History

History
255 lines (180 loc) · 5.71 KB

INSTALL.md

File metadata and controls

255 lines (180 loc) · 5.71 KB
Raw

HotPlex Installation Guide

This guide covers installation and configuration on various platforms.

简体中文

Quick Start

One-Click Install (Linux / macOS / WSL)

curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash

Install Specific Version

# Download and run with version flag
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -v v0.22.0

Note: -- separates bash options from script options. Without it, -v would be interpreted by bash instead of the script.

Custom Install Directory

curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -d ~/bin

Dry Run Mode

# Preview actions without executing
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -n

Force Reinstall

# Overwrite existing same version
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -f

Verbose Output

# Show detailed debug info
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -V

System Requirements

Platform Architecture Support
Linux amd64, arm64 ✅
macOS amd64 (Intel), arm64 (Apple Silicon) ✅
Windows WSL2 ✅

Dependencies:

  • curl or wget
  • tar (Linux/macOS) or unzip (Windows)

Install Options

Option Description
-v, --version Specify version (default: latest)
-d, --dir Install directory (default: /usr/local/bin)
-c, --config Generate config files only
-u, --uninstall Uninstall HotPlex
-f, --force Force reinstall
-n, --dry-run Dry run mode, show actions without executing
-q, --quiet Quiet mode
-V, --verbose Verbose output
--skip-verify Skip checksum verification
--skip-wizard Skip post-install setup wizard
--non-interactive Non-interactive mode
-h, --help Show help
--version Show script version

Manual Install

1. Download Binary

Download from Releases:

# Linux amd64
curl -LO https://github.com/hrygo/hotplex/releases/download/v0.33.0/hotplex_0.33.0_linux_amd64.tar.gz

# macOS arm64 (Apple Silicon)
curl -LO https://github.com/hrygo/hotplex/releases/download/v0.33.0/hotplex_0.33.0_darwin_arm64.tar.gz

2. Extract and Install

tar -xzf hotplex_0.33.0_linux_amd64.tar.gz
sudo mv hotplexd /usr/local/bin/
sudo chmod +x /usr/local/bin/hotplexd

3. Verify

hotplexd version

Configuration

Generate Config Template

# Generate config files only
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -c

Config file is created by default at ~/.config/hotplex/.env (XDG standard path)

Required Settings

Edit ~/.config/hotplex/.env:

# API security token (required for production)
HOTPLEX_API_KEY=your-secure-api-key

# Slack Bot config
HOTPLEX_SLACK_PRIMARY_OWNER=UXXXXXXXXXX
HOTPLEX_SLACK_BOT_USER_ID=UXXXXXXXXXX
HOTPLEX_SLACK_BOT_TOKEN=xoxb-your-token
HOTPLEX_SLACK_APP_TOKEN=xapp-your-token

# GitHub Token (for Git operations)
GITHUB_TOKEN=ghp_your-token

Config File Search Order

HotPlex follows the XDG specification and searches for config in this order:

  1. Path specified by --env-file flag
  2. Path specified by ENV_FILE environment variable
  3. .env in current directory
  4. ~/.config/hotplex/.env (standard path on macOS/Linux)

Start Service

# Default config (auto-searches for .env and server.yaml)
hotplexd start

# Specify config files explicitly
hotplexd start --env-file ~/.config/hotplex/.env --config ~/.config/hotplex/server.yaml

# Show help
hotplexd start --help

Docker Deployment

# Pull image (choose your stack: base, node, python, rust, java, or full)
docker pull ghcr.io/hrygo/hotplex:node

# Run container
docker run -d \
  --name hotplex \
  -p 8080:8080 \
  -p 9080:9080 \
  -v ~/.config/hotplex:/root/.hotplex \
  -v ~/projects:/root/projects \
  -e HOTPLEX_ADMIN_PORT=9080 \
  -e HOTPLEX_API_KEY=your-secure-api-key \
  ghcr.io/hrygo/hotplex:node

Ports:

  • 8080: Main WebSocket/HTTP API server
  • 9080: Admin API for session management and diagnostics

CLI Commands

After starting the container, use docker exec to run CLI commands:

# Check version
docker exec hotplex hotplexd version

# List active sessions
docker exec hotplex hotplexd session list

# Run diagnostics
docker exec hotplex hotplexd doctor

# Validate config
docker exec hotplex hotplexd config validate /root/.hotplex/config.yaml

# Terminate a session
docker exec hotplex hotplexd --admin-token=your-token session kill <session-id>

Uninstall

curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash -s -- -u

Or manual removal:

sudo rm /usr/local/bin/hotplexd
# Optional: remove config
rm -rf ~/.config/hotplex

Troubleshooting

Permission Issues

If installing to /usr/local/bin fails:

# Use sudo
curl -sL ... | sudo bash

# Or install to user directory
curl -sL ... | bash -s -- -d ~/.local/bin

Command Not Found

Ensure install directory is in PATH:

echo $PATH
# Add to ~/.bashrc or ~/.zshrc if missing
export PATH="$HOME/.local/bin:$PATH"

Version Mismatch

Clear cache and reinstall:

rm -rf /tmp/hotplex-*
curl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash

Next Steps