Installing Apps Tools And Services

Key Information to Note:

• OS: Ubuntu/Debian-based Linux
• Architecture: x86_64
• Package managers: uv (Python), bun (Node), mise (version management)
• Native services: PostgreSQL, Redis
• Docker network: proxy (system-wide Traefik network)
• Domain conventions: *.delo.sh for services

2. Gather Data on Thing Being Installed

Use Official Channels:

• Check main GitHub repository (README, installation docs)
• Review official documentation site
• Examine release notes and installation guides
• Look for Docker Compose examples if applicable
• Check for .env.example or configuration templates

Critical Questions:

• What runtime does it require? (Python, Node, Rust, Go?)
• Is it a CLI tool, library, or service?
• Does it need a database? (Can we use native Postgres/Redis?)
• Does it expose HTTP endpoints? (Needs Traefik integration?)
• What secrets/API keys does it need? (Check ~/.config/zshyzsh/secrets.zsh)

3. Determine Installation Method

Decision Tree:

Is it available in the mise registry?
├─ Yes? → mise install <package> #easy peasy done!

Is it Python-based?
├─ CLI tool → uv tool install
├─ Library → uv pip install -g
└─ Service → Docker or uv pip install -g

Is it Node/JS/TS-based?
├─ CLI tool → bun install -g or bunx (one-offs)
├─ Library → bun add
└─ Service → Docker or native bun

Is it containerized?
└─ Follow Docker/Containerized Workflow

Is it from GitHub?
└─ Clone to ~/code and apply appropriate install method

Python Applications

Core Principles

ALWAYS use uv as the package tool

• Prefer global installs over venv
• Use mise-managed uv and python
• End goal: invoke as someApp, not uv run someApp
• Preferred bin path: ~/.local/bin

Installation Patterns

CLI Tools:

# Use uv tool install for CLI tools
uv tool install <package-name>

# Verify installation
which <tool-name>
<tool-name> --version

Example - Installing ruff:

# Install globally as CLI tool
uv tool install ruff

# Verify
ruff --version

Libraries/Packages:

# Use uv sync first if pyproject allows
uv sync

# Use global install instead of pip install
uv pip install -g <package-name>

# If docs say "pip install -r requirements.txt", translate to:
uv pip install -r requirements.txt

Services (Python-based):

For services like FastAPI apps, Agno agents, etc.:

# Clone to ~/code if from GitHub
cd ~/code
gh repo clone <repo-url>
cd <project-name>

# Install dependencies globally or in project
uv sync

# Or use project-specific environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Tool Replacements

Replace these commands:

• pip install → uv pip install -g
• pipx install → uv tool install
• python -m venv → uv venv (if venv needed)

Mise Integration

Ensure mise manages Python and uv:

# Check current versions
mise ls --current

# Install/update if needed
mise use python@latest uv@latest -g

# Verify
which python
which uv

# Explicitly invoke
mise x -- uv --version
mise x [email protected] -- python --version

Node/JavaScript/TypeScript Applications

Core Principles

Prefer bun over npm

• Use mise-managed bun/nodejs
• Use globally installed tools
• Use latest bun/nodejs versions
• OK to use npx or bunx for one-off commands

Installation Patterns

CLI Tools:

# Global installation with bun
bun install -g <package-name>

# Verify
which <tool-name>
<tool-name> --version

Example - Installing typescript:

# Install globally
bun install -g typescript

# Verify
tsc --version

One-off Commands:

# Use bunx for one-time executions
bunx create-react-app my-app
bunx prettier --write .

Project Dependencies:

# For project-specific packages
cd ~/code/<project-name>
bun install
bun add <package-name>

Mise Integration

Ensure mise manages bun/node:

# Install/update globally
mise use bun@latest -g
mise use node@latest -g

# Verify
which bun
which node
bun --version
node --version

GitHub-Sourced Installations

Core Principle

Always clone into ~/code

Workflow

# 1. Clone to standard location
cd ~/code
git clone <repo-url>
cd <project-name>

# 2. Initialize with iMi (optional, if it's a project you'll develop)
imi init

# 3. Apply appropriate installation method based on type
# - Python: uv pip install -g -r requirements.txt
# - Node: bun install
# - Rust: cargo install --path .
# - Go: go install

Example - Installing a Python CLI from GitHub:

cd ~/code
git clone https://github.com/user/awesome-tool
cd awesome-tool

# Install as tool
uv tool install .

# Or if it has requirements
uv pip install -g -r requirements.txt
uv pip install -g .

Docker/Containerized Installations

Core Principles

Ecosystem Integration:

1. Modify compose files to fit Docker container ecosystem
2. Avoid common port conflicts (3000, 8080, etc.)
3. Use system-wide proxy network for Traefik integration
4. Connect to native services (Postgres, Redis, Neo4j, Qdrant)
5. Use simple, common-sense subdomains (*.delo.sh)

Workflow

1. Examine and Modify Compose File

Critical Modifications:

# docker-compose.yml